Azure DevOps Server (Python)

Model Context Protocol (MCP) server for Azure DevOps integration, enabling AI assistants (Claude Desktop, OpenCode.ai) to interact with work items, test results, Git repositories, and analyze work item dependencies.

Supported Platforms:

• ✅ Claude Desktop - Anthropic's desktop application
• ✅ OpenCode.ai - Terminal-based AI coding agent

Features

• Work Items: Get work items by ID, query with filters, execute WIQL queries
• Saved Queries: Execute saved Azure DevOps queries by ID
• Dependency Analysis: Analyze work item relationships and dependencies
• Test Results: Access test runs and test results
• Git Repositories: Browse repositories, commits, and pull requests
• WIQL Support: Build and execute custom Work Item Query Language queries
• Generic Deployment: Works with cloud and on-premise Azure DevOps (SSL verification disabled by default)
• Multi-Project Support: Configure multiple Azure DevOps project base URLs and select per tool invocation
• Project Enumeration: list_projects tool returns configured shortnames and base URLs
• Request Timeout: Optional timeout in AZDO_CONFIG (seconds) to bound network calls

Quick Start (Automated Installation)

Prerequisites

• Python 3.8 or higher
• Claude Desktop installed
• Azure DevOps Personal Access Token (PAT) with permissions:
  • Work Items: Read
  • Code: Read
  • Test: Read

Install

Run the installation script with PowerShell:

./install.ps1

You will be prompted to enter your Azure DevOps Personal Access Token. The script will:

• Install Python dependencies
• Backup your existing Claude Desktop configuration
• Add the MCP server to your configuration
• Create (or reuse) a unified JSON configuration file referenced by AZDO_CONFIG

Parameters:

Parameter	Description	Example
-Projects	Semicolon-separated shortname=baseUrl pairs (baseUrl must include project path)	"default=https://dev.azure.com/Org/ProjectA;neo=https://dev.azure.com/Org/ProjectNeo"
-Pat	Personal Access Token (if omitted you will be prompted)	"azdopat123"
-PythonPath	Python executable to use	"python"
-ConfigPath	Path for generated AZDO config file (optional)	"C:\path\azure_devops_config.json"

Custom Configuration Example:

./install.ps1 -Projects "default=https://dev.azure.com/Org/ProjectA;neo=https://dev.azure.com/Org/ProjectNeo" -Pat "your-pat-token" -PythonPath "python" -ConfigPath "C:\path\azure_devops_config.json"

Uninstall

./uninstall.ps1

Removes the server from Claude Desktop and creates a timestamped backup of the config. By default the AZDO_CONFIG file containing project definitions and PATs is retained.

Optional removal of AZDO_CONFIG:

./uninstall.ps1 -RemoveConfig

When -RemoveConfig is supplied the script prompts for confirmation (must type YES) then attempts to delete the JSON file referenced by the server's AZDO_CONFIG environment entry (if it exists). Use this only if you no longer need the per-project PAT configuration.

Setup for OpenCode.ai

OpenCode is an AI coding agent for the terminal that supports MCP servers. You can add this Azure DevOps MCP server to OpenCode to interact with your Azure DevOps projects directly from your terminal.

1. Install Dependencies

pip install -r requirements.txt

2. Configure Azure DevOps Connection

Create your Azure DevOps configuration file (see Configuration section below for details):

cp azure_devops_config.example.json azure_devops_config.json
# Edit azure_devops_config.json with your baseUrl and PAT

3. Add to OpenCode Configuration

Copy the example OpenCode configuration:

cp opencode.example.jsonc opencode.jsonc

Then edit opencode.jsonc and update the paths:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "azure-devops": {
      "type": "local",
      "command": ["python", "/absolute/path/to/mcp_azure_devops/src/server.py"],
      "enabled": true,
      "environment": {
        "AZDO_CONFIG": "/absolute/path/to/azure_devops_config.json",
        "AZDO_LOG_LEVEL": "info"
      },
      "timeout": 10000
    }
  }
}

Important: Replace /absolute/path/to/ with the actual absolute paths on your system.

4. Start OpenCode

Navigate to your project and start OpenCode:

cd /path/to/your/project
opencode

5. Use Azure DevOps Tools

You can now use Azure DevOps tools in your prompts:

List all configured Azure DevOps projects

Get work item 123 from the default project

Query by ID 02576c96-99fa-472b-8929-80b5f1760b02 and show the results

For better performance, you can configure OpenCode to only enable Azure DevOps tools for specific agents. See opencode.example.jsonc for examples.

Manual Setup (Claude Desktop)

1. Install Dependencies

pip install -r requirements.txt

2. Configure Claude Desktop

Add the server configuration to your Claude Desktop config file:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "azure-devops": {
      "command": "python",
      "args": ["C:/path/to/mcp_azure_devops/src/server.py"],
      "env": {
        "AZDO_CONFIG": "C:/path/to/azure_devops_config.json"
      }
    }
  }
}

Sample azure_devops_config.json:

{
  "projects": {
    "iris": { "baseUrl": "https://dev.azure.com/Org/ProjectIris", "pat": "xxxxx" },
    "neo":  { "baseUrl": "https://dev.azure.com/Org/ProjectNeo",  "pat": "yyyyy" }
  },
  "timeout": 15
}

Important:

• Update the path in args to match your installation directory
• Replace placeholder PATs with valid tokens (do NOT commit real PATs)
• Each baseUrl includes organization + project path (no trailing slash)
• Configuration is loaded exclusively from AZDO_CONFIG; legacy env vars (AZURE_DEVOPS_BASE_URL, AZURE_DEVOPS_PAT, etc.) are deprecated and ignored by the current implementation.

Multi-Project Configuration (Per-Project PATs)

Multiple projects are defined exclusively via the AZDO_CONFIG JSON file (see above). Each project entry includes its own baseUrl and pat.

Key points:

• baseUrl must include the full organization + project path.
• pat must have scopes: Work Items Read, Code Read, Test Read.
• If default shortname exists it is used when project argument is omitted; else the first project is chosen.
• timeout (optional) applies uniformly to all requests.

To add a new project, edit azure_devops_config.json and restart Claude Desktop.

Claude tool call example (conceptual):

• "Get work item 123 from project neo" (internally sets { "project": "neo", "id": 123 })
• If no project is specified, the server uses default if present, else the first configured project.

3. Restart Claude Desktop

After adding the configuration, restart Claude Desktop to load the MCP server.

Available Tools

All tools accept an optional project parameter (string shortname) unless noted otherwise.

get_work_item

Get a work item by ID.

Parameters:
- project: (Optional) Project shortname
- id: Work item ID (number)
- fields: (Optional) Array of specific fields to retrieve

query_by_id

Execute a saved query by its ID.

Parameters:
- project: (Optional) Project shortname
- queryId: Query ID (GUID format, e.g., "02576c96-99fa-472b-8929-80b5f1760b02")
- fields: (Optional) Specific fields to retrieve. If not provided, uses query's own columns

get_linked_work_items

Get work items from a query and analyze their dependencies/links.

Parameters:
- project: (Optional) Project shortname
- queryId: Query ID (GUID format)
- linkType: (Optional) Filter by link type: "Children", "Parent", "Related", "Tested By"
- fields: (Optional) Specific fields to retrieve

Example: Get all tasks (children) linked to bugs from a query

get_work_items_with_relations

Get work items with their relationship details (parent, children, related items, etc.).

Parameters:
- project: (Optional) Project shortname
- ids: Array of work item IDs
- fields: (Optional) Specific fields to retrieve

query_work_items

Query work items using field filters.

Parameters:
- project: (Optional) Project shortname
- fields: Array of field names to return (e.g., ["System.Id", "System.Title"])
- filters: Object with filter conditions (e.g., {"System.State": "Active"})
- top: Maximum number of results (default: 50)

execute_wiql

Execute a custom WIQL query.

Parameters:
- project: (Optional) Project shortname
- wiql: WIQL query string
Example: "SELECT [System.Id], [System.Title] FROM WorkItems WHERE [System.WorkItemType] = 'Bug'"

get_test_runs

Get recent test runs.

Parameters:
- project: (Optional) Project shortname
- top: Maximum number of test runs to return (default: 10)

get_test_results

Get test results for a specific test run.

Parameters:
- project: (Optional) Project shortname
- runId: Test run ID (number)

get_repositories

Get all Git repositories in the project.

Parameters:
- project: (Optional) Project shortname

get_commits

Get commits from a Git repository.

Parameters:
- project: (Optional) Project shortname
- repositoryId: Repository ID or name
- top: Maximum number of commits (default: 20)

get_pull_requests

Get pull requests from a Git repository.

Parameters:
- project: (Optional) Project shortname
- repositoryId: Repository ID or name
- status: PR status filter (active, completed, abandoned, all) (default: active)

list_projects

List configured project shortnames and their base URLs.

Parameters:
(none)
Returns: Array of { shortname, baseUrl }
Example: "List configured Azure DevOps projects"

ping

Health check summarizing server configuration.

Parameters:
(none)
Returns JSON object:
{
  "serverVersion": "1.0.0",
  "projects": [ { "shortname": "default", "baseUrl": "https://dev.azure.com/Org/ProjectA" }, ... ],
  "timeout": 15,
  "timestamp": "2025-11-03T12:34:56.789012Z"
}

Example prompt: "Ping the Azure DevOps server" or "Health check"

Usage Examples

Once configured, you can use natural language to interact with Azure DevOps:

Work Items & Queries

• "Query by ID 02576c96-99fa-472b-8929-80b5f1760b02 and create a table"
• "Get work item 100"
• "Show me all active bugs"
• "Query work items where System.State is Active"
• "In project iris get work item 200"

Dependency Analysis

• "Give me all tasks linked to work items from query id a5ff7f63-ea7b-4b2e-9528-61513f744570"
• "Show me all children of work items from query [query-id] in project neo"
• "Analyze dependencies for work items 100, 200, 300"

Test Results

• "Get the latest test runs"
• "Show me test results for run 456 in project iris"

Git Operations

• "List all Git repositories"
• "Show recent commits in repository MyRepo"
• "Get active pull requests in MyRepo for project neo"

Project Enumeration

• "List configured Azure DevOps projects"
• "Show projects"

OpenCode-Specific Examples

When using OpenCode, you can also add instructions to your AGENTS.md file to automatically use Azure DevOps tools:

AGENTS.md:

## Azure DevOps Integration

When working with work items, bugs, or tasks:
- Use Azure DevOps tools to query work items
- Use `list_projects` to see available projects
- Use `get_linked_work_items` for dependency analysis

When analyzing test failures:
- Use `get_test_runs` to see recent test executions
- Use `get_test_results` to investigate specific test failures

Example OpenCode Prompts:

• "Show me all bugs assigned to me in the current sprint"
• "Analyze the test failures from the last 5 test runs"
• "Create a dependency graph for work item 456 showing all parent and child items"
• "List all active pull requests in the MyRepo repository and summarize their status"

Configuration

JSON + Optional .env Overlay

Primary configuration remains the JSON file referenced by AZDO_CONFIG. Optionally you can supply or override project entries via environment variables or a .env file without editing the JSON (useful for keeping secrets out of tracked files).

Activation methods:

• Set AZDO_USE_ENV=1 (process env) OR
• Set AZDO_ENV_PATH to a custom dotenv file path (e.g. C:\secrets\azuredevops.env). If present this also activates overlay.
• Default dotenv path is ./.env if it exists.

Variable naming pattern (case sensitive):

AZDO_PROJECT_<SHORTNAME>_BASE_URL=https://dev.azure.com/Org/ProjectPath
AZDO_PROJECT_<SHORTNAME>_PAT=your_pat_token_here
AZDO_TIMEOUT=20  # optional timeout override in seconds

Example .env:

# Azure DevOps MCP server secrets (DO NOT COMMIT)
AZDO_PROJECT_default_BASE_URL=https://dev.azure.com/Org/ProjectA
AZDO_PROJECT_default_PAT=pat_default_secret
AZDO_PROJECT_neo_BASE_URL=https://dev.azure.com/Org/ProjectNeo
AZDO_PROJECT_neo_PAT=pat_neo_secret
AZDO_TIMEOUT=25

Behavior:

• Overlay project entries override same shortnames from JSON.
• Shortname discovery is based on matching both BASE_URL and PAT variables; partial definitions are ignored.
• Trailing slashes are trimmed automatically.
• Timeout override uses AZDO_TIMEOUT if numeric.
• Final configuration must contain at least one valid project (baseUrl + pat) or startup exits.

Security:

• Root .env template is committed (contains only placeholders) while other secret variants remain ignored.
• Never commit real PAT values; replace placeholders locally or use a non-tracked .env.local file or system environment.

Below is the original JSON-only description for reference (now extended for overlay-only mode):

The server loads configuration primarily from AZDO_CONFIG (path to JSON file). Legacy environment variables (AZURE_DEVOPS_BASE_URL, AZURE_DEVOPS_PAT, AZURE_DEVOPS_PROJECTS_FILE, AZURE_DEVOPS_PROJECTS, AZURE_DEVOPS_TIMEOUT) are deprecated and ignored.

Required file structure (JSON base):

{
  "projects": {
    "shortname": { "baseUrl": "https://dev.azure.com/Org/ProjectPath", "pat": "your-pat" }
  },
  "timeout": 15
}

Overlay-only minimal example (all real data provided via environment / .env):

{
  "projects": {},
  "timeout": 15
}

• projects must be a non-empty object unless overlay is active (AZDO_USE_ENV=1 or AZDO_ENV_PATH set) and supplies valid project entries.
• Each project (from JSON or overlay) must include baseUrl and pat.
• timeout is optional (seconds).

SSL Configuration

The server supports both cloud and on-premise Azure DevOps instances. SSL verification is disabled by default (verify=False) to ensure compatibility across different environments. Users deploying in highly secure environments can implement certificate pinning separately if needed.

Structured Logging

The server supports optional structured JSON logging to stderr for debugging and monitoring. Logging is controlled by the AZDO_LOG_LEVEL environment variable.

Log Levels:

• none (default): No logging output
• info: Log tool invocations with timestamp, tool name, project, duration, and success/error status
• debug: Include all info-level data plus sanitized tool parameters

Configuration:

Add AZDO_LOG_LEVEL to the server environment in Claude Desktop config:

{
  "mcpServers": {
    "azure-devops": {
      "command": "python",
      "args": ["C:/path/to/mcp_azure_devops/src/server.py"],
      "env": {
        "AZDO_CONFIG": "C:/path/to/azure_devops_config.json",
        "AZDO_LOG_LEVEL": "info"
      }
    }
  }
}

Log Format (JSON to stderr):

{
  "timestamp": "2025-11-03T12:34:56.789012Z",
  "level": "INFO",
  "tool": "get_work_item",
  "project": "default",
  "duration_ms": 123.45,
  "status": "success",
  "error": null,
  "params": {...}
}

Viewing Logs:

On Windows, logs are written to:

%APPDATA%\Claude\logs\mcp-server-azure-devops.log

On macOS:

~/Library/Logs/Claude/mcp-server-azure-devops.log

Notes:

• Logging writes to stderr and does not interfere with MCP stdio protocol
• Sensitive data (PAT) is never logged
• Logging errors never crash the server
• Use info level for production monitoring
• Use debug level for troubleshooting (includes request parameters)

Security Notes

⚠️ Important:

• Your PAT (Personal Access Token) is stored in the Claude Desktop configuration file
• Ensure this file has appropriate permissions and is not shared or committed to version control
• The installation script creates automatic backups of your Claude Desktop configuration
• Backups are stored in %APPDATA%\Claude\ with timestamps

Testing

Set the AZDO_CONFIG environment variable before running tests:

Windows (PowerShell):

$env:AZDO_CONFIG = "C:\path\azure_devops_config.json"
python tests/test_client.py

macOS/Linux (bash):

export AZDO_CONFIG=/path/azure_devops_config.json
python tests/test_client.py

Run All Tests

python tests/test_client.py

Test Dependency Analysis

python tests/test_dependencies.py

Multi-Project Integration Test

python tests/test_integration.py

Manual Testing

Test specific queries:

python tests/test_dependencies.py

Troubleshooting

Server not showing in Claude Desktop

1. Check if Claude Desktop config is valid JSON
2. Verify the path to src/server.py is correct
3. Check Claude Desktop logs: %APPDATA%\Claude\logs\mcp-server-azure-devops.log
4. Restart Claude Desktop

401 Authentication Error

1. Verify your PAT is valid and not expired
2. Ensure PAT has required permissions (Work Items: Read, Code: Read, Test: Read)
3. Check if you can access the Azure DevOps URL in your browser

SSL Issues

1. Verify you can access the Azure DevOps URL directly in a browser
2. Check firewall/proxy settings if behind a corporate network
3. SSL verification is disabled by default; if you need certificate pinning, implement it separately

Query by ID not working

1. Verify the query ID is correct (GUID format)
2. Ensure you have access to the query in Azure DevOps
3. Check if the query exists in the specified project

ImportError or Module Not Found

1. Ensure all dependencies are installed: pip install -r requirements.txt
2. Verify Python version is 3.8 or higher: python --version

OpenCode.ai Issues

MCP Server Not Loading

1. Check that paths in opencode.jsonc are absolute paths
2. Verify AZDO_CONFIG path points to a valid configuration file
3. Check OpenCode logs: Run opencode with increased verbosity
4. Ensure Python is in your PATH: which python or where python

Tools Not Available

1. Verify the MCP server is enabled: "enabled": true in opencode.jsonc
2. Check if tools are disabled globally in the tools section
3. Restart OpenCode after configuration changes

High Token Usage

1. Consider disabling Azure DevOps tools globally and enabling per-agent
2. Use the /undo command if a tool returns too much data
3. Be specific in your prompts to target specific work items or queries

Project Structure

mcp_azure_devops/
├── src/
│   ├── server.py                      # MCP server implementation
│   ├── config.py                      # Unified config loader (AZDO_CONFIG)
│   ├── logging_utils.py               # Structured JSON logging
│   └── client.py                      # Azure DevOps REST API client
├── tests/
│   ├── test_client.py                 # Tool invocation tests
│   ├── test_dependencies.py           # Dependency analysis tests
│   ├── test_integration.py            # Multi-project integration tests
│   ├── test_logging.py                # Logging functionality tests
│   ├── test_mock.py                   # Offline mock data tests
│   ├── test_ping.py                   # Health check tests
│   └── test_mock_client.py            # Mock client for testing
├── reviews/
│   ├── README.md                      # Review process documentation
│   └── YYYYMMDD_HHMMSS_*.md          # Timestamped review documents
├── azure_devops_config.example.json   # Example Azure DevOps configuration
├── azure_devops_config.json           # User configuration (gitignored)
├── opencode.example.jsonc             # Example OpenCode.ai configuration
├── install.ps1                        # Installation script (Claude Desktop)
├── uninstall.ps1                      # Uninstallation script (Claude Desktop)
├── requirements.txt                   # Python dependencies
├── .env                               # Environment variable template
├── .gitignore
├── CONTEXT.md                         # Requirements documentation
└── README.md                          # This file

Development

Based on proven Azure DevOps client code from the DvoiPad project, ensuring reliability and compatibility with enterprise Azure DevOps instances.

License

MIT