MCP Azure DevOps Server

A Model Context Protocol (MCP) server for Azure DevOps integration, enabling AI assistants to interact with Azure DevOps Work Items, Git Repositories, Pull Requests, and Pipelines.

Note: Flow metrics, WIP analysis, and other analytics features were removed. With ActivatedDate and ClosedDate now exposed on all work item queries, Claude can derive cycle time, lead time, aging, and throughput directly from the data — no pre-built analytics tools needed.

---

Quick Start

Get up and running in 3 steps:

1. Clone and configure

git clone https://github.com/viamus/mcp-azure-devops.git
cd mcp-azure-devops

Option A — .env file (recommended for Docker):

cp .env.example .env
# Edit .env with your Azure DevOps credentials

Option B — appsettings.json (for .NET CLI):

Edit src/Viamus.Azure.Devops.Mcp.Server/appsettings.json with your Azure DevOps credentials:

{
  "AzureDevOps": {
    "OrganizationUrl": "https://dev.azure.com/your-organization",
    "PersonalAccessToken": "your-personal-access-token",
    "DefaultProject": "your-project-name"
  }
}

For multiple Azure DevOps organizations or PATs, keep one entry per organization and select it in tool calls with the optional organization argument:

{
  "AzureDevOps": {
    "DefaultOrganization": "primary",
    "Organizations": [
      {
        "Name": "primary",
        "OrganizationUrl": "https://dev.azure.com/primary-org",
        "PersonalAccessToken": "primary-pat",
        "DefaultProject": "primary-project"
      },
      {
        "Name": "secondary",
        "OrganizationUrl": "https://dev.azure.com/secondary-org",
        "PersonalAccessToken": "secondary-pat",
        "DefaultProject": "secondary-project"
      }
    ]
  }
}

Need a PAT? See Creating a Personal Access Token below.

2. Run the server

Option A - Docker (recommended):

docker compose up -d
# Server runs at http://localhost:8080 (use reverse proxy for HTTPS in production)

Option B - .NET CLI:

dotnet run --project src/Viamus.Azure.Devops.Mcp.Server
# Server runs at http://localhost:5000

3. Verify it's working

# Docker
curl http://localhost:8080/health

# .NET CLI
curl http://localhost:5000/health

You should see: Healthy

---

Automated Installation (Windows)

For Windows users, a PowerShell script is available that automates the entire setup process:

# Download and run the installer (as Administrator)
irm https://raw.githubusercontent.com/viamus/mcp-azure-devops/main/install-mcp-azure-devops.ps1 -OutFile install-mcp-azure-devops.ps1

.\install-mcp-azure-devops.ps1 `
    -OrganizationUrl "https://dev.azure.com/your-organization" `
    -PersonalAccessToken "your-pat-token" `
    -DefaultProject "your-project-name" `
    -ApiKey "your-secure-api-key"  # Optional: enables API key authentication

The script will automatically:

• Install .NET 10 SDK (if not present)
• Install Node.js (if not present)
• Install Claude Code CLI (if not present)
• Clone the repository
• Configure your Azure DevOps credentials
• Register the MCP server with Claude Code (HTTPS transport)

For multiple organizations/PATs, run the installer for the primary organization, then add AzureDevOps:Organizations entries to appsettings.json or use the Docker environment variables from .env.example.

After installation, start the server:

cd $env:USERPROFILE\mcp-azure-devops
dotnet run --project src/Viamus.Azure.Devops.Mcp.Server

---

About

This project implements an MCP server that exposes tools for querying and managing Work Items and Git Repositories in Azure DevOps. It can be used with any compatible MCP client, such as Claude Desktop, Claude Code, or other assistants that support the protocol.

---

Available Tools

Work Item Tools

| Tool | Description | |------|-------------| | get_work_item | Gets details of a specific work item by ID (supports optional includeRelations parameter) | | get_work_items | Gets multiple work items by IDs (batch retrieval, supports optional includeRelations parameter) | | get_work_item_relations | Gets the normalized list of relationships (Parent, Child, Related, Predecessor, Successor, Tests, Tested By, Hyperlink, Attachment) associated with a work item | | get_work_item_tree | Recursively gets parent and child work items starting from a root work item, up to a specified depth limit. Includes cycle detection | | query_work_items | Queries work items using WIQL (Work Item Query Language) | | get_work_items_by_state | Filters work items by state (Active, New, Closed, etc.) | | get_work_items_assigned_to | Gets work items assigned to a specific user | | get_child_work_items | Gets child work items of a parent work item | | get_recent_work_items | Gets recently changed work items | | search_work_items | Searches work items by title text | | add_work_item_comment | Adds a comment to a specific work item | | get_work_item_comments | Reads comments (discussion history) of a work item, with pagination, sort order, and optional rendered HTML | | create_work_item | Creates a new work item (Bug, Task, User Story, etc.) with support for all standard fields, parent linking, and custom fields | | update_work_item | Updates an existing work item. Only specified fields are changed; omitted fields remain unchanged | | link_work_items | Links an existing work item to parent, child, predecessor, successor, or related work items |

Git Repository Tools

| Tool | Description | |------|-------------| | get_repositories | Lists all Git repositories in a project | | get_repository | Gets details of a specific repository by name or ID | | get_branches | Lists all branches in a repository | | get_repository_items | Browses files and folders at a specific path in a repository | | get_file_content | Gets the content of a specific file in a repository | | search_repository_files | Searches for files by path pattern in a repository |

Pull Request Tools

| Tool | Description | |------|-------------| | get_pull_requests | Lists pull requests with optional filters (status, creator, reviewer, branches) | | get_pull_request | Gets details of a specific pull request by ID within a repository | | get_pull_request_by_id | Gets details of a pull request by ID only, searching across all repositories in the project | | get_pull_request_threads | Gets comment threads for a pull request | | create_pull_request_thread | Creates a new comment thread on a pull request, either as a general discussion or inline file comment | | update_pull_request_thread_status | Updates a pull request comment thread status, including close/resolve aliases | | search_pull_requests | Searches pull requests by text in title or description | | query_pull_requests | Advanced query with multiple combined filters | | create_pull_request | Creates a new pull request with title, description, source/target branches, draft flag, reviewers, and linked work items | | update_pull_request | Updates an existing pull request title, description, target branch, status, or draft flag |

Pipeline/Build Tools

| Tool | Description | |------|-------------| | get_pipelines | Lists all pipelines (build definitions) in a project | | get_pipeline | Gets details of a specific pipeline by ID | | get_pipeline_runs | Gets recent runs (builds) for a specific pipeline | | get_build | Gets details of a specific build by ID | | get_builds | Lists builds with optional filters (status, result, branch, requester) | | get_build_logs | Gets the list of log files for a build | | get_build_log_content | Gets the content of a specific build log | | get_build_timeline | Gets the timeline (stages, jobs, tasks) for a build | | query_builds | Advanced query with multiple combined filters |

---

Prerequisites

| Requirement | Version | Notes | |-------------|---------|-------| | .NET SDK | 10.0+ | Required for local development | | Docker | Latest | Recommended for running | | Azure DevOps Account | - | With Personal Access Token |

Creating a Personal Access Token (PAT)

1. Go to your Azure DevOps organization: https://dev.azure.com/{your-org}
2. Click on User Settings (gear icon) > Personal Access Tokens
3. Click + New Token
4. Configure:
   • Name: MCP Server (or any name you prefer)
   • Expiration: Choose based on your needs
   • Scopes: Select the following permissions:

| Scope | Permission | Required for | |-------|------------|--------------| | Work Items | Read & Write | Get, query, create, update work items and add comments | | Code | Read & Write | Git repositories, branches, files, and pull requests (Write required to create PRs) | | Build | Read | Pipelines and builds |

5. Click Create and copy the token immediately (you won't see it again!)

Multiple Organizations / PATs

The server supports one PAT per configured Azure DevOps organization. Existing single-organization settings still work:

• AzureDevOps:OrganizationUrl
• AzureDevOps:PersonalAccessToken
• AzureDevOps:DefaultProject

For multiple PATs, configure AzureDevOps:Organizations with Name, OrganizationUrl, PersonalAccessToken, and optional DefaultProject. Set AzureDevOps:DefaultOrganization to choose the fallback organization. Tool calls can pass organization as the configured Name, the full organization URL, or the organization slug from https://dev.azure.com/{slug}.

---

Running Options

Option 1: Docker Compose (Recommended)

Best for: Production use, quick setup without .NET installed

1. Create your .env file from the template:

   cp .env.example .env
   # Edit .env with your Azure DevOps credentials
   

   For multiple organizations/PATs, fill AZURE_DEVOPS_ORGANIZATION_0_*, AZURE_DEVOPS_ORGANIZATION_1_*, and AZURE_DEVOPS_DEFAULT_ORGANIZATION in .env.

2. Start the server:

   docker compose up -d
   

Server URL: http://localhost:8080 (internal)

Important: For production, use a reverse proxy (nginx, traefik, or a cloud load balancer) in front of the container to provide HTTPS/TLS termination.

Useful commands:

docker compose logs -f          # View logs
docker compose down             # Stop the server
docker compose up -d --build    # Rebuild and start

Option 2: .NET CLI

Best for: Development, debugging

dotnet run --project src/Viamus.Azure.Devops.Mcp.Server

Server URL: http://localhost:5000

HTTPS Support: The server can also run with HTTPS on port 5001, but this may cause certificate validation issues with some MCP clients (e.g., Claude Code). If you need HTTPS locally, configure the development certificate properly:

# Trust the development certificate (first time only)
dotnet dev-certs https --trust

# Run with HTTPS
dotnet run --project src/Viamus.Azure.Devops.Mcp.Server --urls "https://localhost:5001"

For production environments, use a reverse proxy with properly configured TLS certificates instead.

Option 3: Self-Contained Executable

Best for: Deployment without .NET runtime

# Windows
dotnet publish src/Viamus.Azure.Devops.Mcp.Server -c Release -r win-x64 -o ./publish/win-x64

# Linux
dotnet publish src/Viam