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, Pipelines, and Wikis over HTTP or local STDIO.
接入你的智能体
從發布者安裝。不是 PlugMCP 端點。
遠端 URL 還是本機指令? 兩種安裝方式的差異
來自發布者
A Model Context Protocol (MCP) server for Azure DevOps integration, enabling AI assistants to interact with Azure DevOps Work Items, Git Repositories, Pull Requests, Pipelines, and Wikis over HTTP or local STDIO.
Azure DevOps MCP for querying repositories, pipelines, work items, and delivery metadata via HTTP
Note: Flow metrics, WIP analysis, and other analytics features were removed. With
ActivatedDateandClosedDatenow 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.
For local process setup, multi-organization configuration, PAT replacement, and error recovery, see the STDIO and error handling guide.
Get up and running in 3 steps:
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.
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
# Docker
curl http://localhost:8080/health
# .NET CLI
curl http://localhost:5000/health
You should receive a JSON response with status: "healthy" and a timestamp. This checks the HTTP host; call an Azure DevOps read tool to validate PAT access.
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:
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
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.
Both hosts expose the same 49 tools. All tools accept an optional organization selector; see Multiple Organizations / PATs.
https://dev.azure.com/{your-org}MCP Server (or any name you prefer)The server supports one PAT per configured Azure DevOps organization. Existing single-organization settings still work:
AzureDevOps:OrganizationUrlAzureDevOps:PersonalAccessTokenAzureDevOps:DefaultProjectFor 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}.
Best for: Production use, quick setup without .NET installed
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.
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
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.
Best for: Deployment without .NET runtime
# Windows
dotnet publish src/Viamus.Azure.Devops.Mcp.Server -c Release --self-contained true -r win-x64 -o ./publish/win-x64
# Linux
dotnet publish src/Viamus.Azure.Devops.Mcp.Server -c Release --self-contained true -r linux-x64 -o ./publish/linux-x64
# macOS (Intel)
dotnet publish src/Viamus.Azure.Devops.Mcp.Server -c Release --self-contained true -r osx-x64 -o ./publish/osx-x64
# macOS (Apple Silicon)
dotnet publish src/Viamus.Azure.Devops.Mcp.Server -c Release --self-contained true -r osx-arm64 -o ./publish/osx-arm64
Then run the executable directly:
# Windows
./publish/win-x64/Viamus.Azure.Devops.Mcp.Server.exe
# Linux/macOS
./publish/linux-x64/Viamus.Azure.Devops.Mcp.Server
Note: For production, use a reverse proxy (nginx, traefik) or Application Gateway to handle TLS termination with your own certificates.
Best for: MCP clients that launch a local process and communicate over stdin/stdout.
The STDIO host uses the same tools, organization/PAT configuration, and error handling as the HTTP server. It does not open a listening port. Build a framework-dependent distribution with the .NET 10 SDK:
dotnet publish src/Viamus.Azure.Devops.Mcp.Stdio -c Release --self-contained false -o ./publish/stdio
Then configure your MCP client's process command. Use an absolute path to the published DLL:
{
"mcpServers": {
"azure-devops": {
"command": "dotnet",
"args": ["C:/path/to/mcp-azure-devops/publish/stdio/Viamus.Azure.Devops.Mcp.Stdio.dll"],
"env": {
"AzureDevOps__OrganizationUrl": "https://dev.azure.com/your-organization",
"AzureDevOps__PersonalAccessToken": "your-pat",
"AzureDevOps__DefaultProject": "your-project"
}
}
}
}
Configuration is loaded from appsettings.json beside the executable, with environment variables and command-line settings taking precedence. The client's working directory can be different. Multi-organization settings use the same keys as HTTP, for example AzureDevOps__Organizations__0__Name and AzureDevOps__Organizations__0__PersonalAccessToken. A .env file is not loaded automatically by the .NET hosts; inject those values through the client or its environment.
All runtime logs go to stderr; stdout is reserved for MCP JSON-RPC messages. Publish/build separately before connecting a client so build output cannot enter the protocol stream. Missing or invalid configuration produces a sanitized startup message on stderr and a nonzero exit code. A stale PAT does not prevent initialization or tool discovery; authentication is attempted when a tool needs Azure DevOps.
For a standalone executable that includes the .NET runtime:
dotnet publish src/Viamus.Azure.Devops.Mcp.Stdio -c Release -r win-x64 --self-contained true -o ./publish/stdio-win-x64
Set the client's command to the absolute path of Viamus.Azure.Devops.Mcp.Stdio.exe and omit args.
The HTTP server supports optional API key authentication to protect your MCP endpoints. STDIO relies on access to the local process and its private configuration; it does not use ServerSecurity settings. Both hosts separately use PATs to authenticate to Azure DevOps.
Add to appsettings.json:
{
"ServerSecurity": {
"ApiKey": "your-secret-api-key",
"RequireApiKey": true
}
}
Or via environment variables:
# .NET CLI
ServerSecurity__ApiKey=your-secret-key ServerSecurity__RequireApiKey=true dotnet run --project src/Viamus.Azure.Devops.Mcp.Server
# Docker — configure in .env file (see .env.example)
docker compose up -d
For Docker, add to your .env file (see .env.example for the full template):
MCP_API_KEY=your-secret-api-key
MCP_REQUIRE_API_KEY=true
RequireApiKey is false (default): No authentication requiredRequireApiKey is true: All requests (except /health) require a valid API key/health endpoint is always accessible without authenticationClients can provide the API key through either header. If both are present, X-API-Key takes precedence.
Option 1 - X-API-Key Header (recommended):
curl -H "X-API-Key: your-secret-key" https://localhost:5001
Option 2 - Authorization: Bearer Header:
curl -H "Authorization: Bearer your-secret-key" https://localhost:5001
Use the configured HTTP/HTTPS URL for your host. These headers contain the MCP API key, not the Azure DevOps PAT.
# Using OpenSSL
openssl rand -base64 32
# Using PowerShell
[Convert]::ToBase64String([Security.Cryptography.RandomNumberGenerator]::GetBytes(32))
Without API Key authentication:
claude mcp add azure-devops --transport http http://localhost:5000
With API Key authentication:
claude mcp add azure-devops --transport http http://localhost:5000 --header "X-API-Key: your-secret-api-key"
Note: Use port
5000(HTTP) if running with .NET CLI, or8080(HTTP) if running with Docker locally. For production deployments, configure a reverse proxy with HTTPS.
After configuring the MCP client, you can ask questions like:
See the operational guide for PAT replacement steps, STDIO diagnostics, and retry guidance. Both transports report failed tool execution with MCP isError: true. Azure DevOps exceptions produce a JSON text content block with stable fields:
{
"error": "Azure DevOps authentication failed. The PAT may be expired, revoked, or invalid. Replace the PAT for the selected organization, check access, and restart the host if configuration changed.",
"errorCode": "AZURE_DEVOPS_AUTHENTICATION_FAILED",
"retryable": false,
"httpStatusCode": 401
}
httpStatusCode can be null when no HTTP response was available. retryable identifies transient failures; the server does not automatically repeat tool calls. Client-requested cancellation remains cancellation. Existing validation and missing-resource JSON responses retain their messages, add the error metadata, and now also set MCP isError: true.
A 401 response cannot establish whether a PAT expired, was revoked, or is invalid. The message lists those possibilities rather than asserting expiration; see Microsoft's PAT guidance. Raw exception messages, credentials, and stack traces are excluded from the new error responses. Wiki lookups return an empty/not-found result only when the requested resource returns HTTP 404. API discovery, authentication, and connectivity failures reach the error handler.
Verify the server is running:
# Docker
docker compose ps
# Check if port is in use
netstat -an | grep 8080 # Docker
netstat -an | grep 5000 # .NET CLI
Check logs for errors:
# Docker
docker compose logs
# .NET CLI - errors appear in terminal
appsettings.jsonorganization value matches a configured Name, URL, or Azure DevOps organization slugIf API key authentication is enabled (RequireApiKey: true):
X-API-Key header is being sent with requests/health endpoint should still work without authentication# Test health endpoint (should work without API key)
curl http://localhost:5000/health
# Test with API key
curl -H "X-API-Key: your-key" http://localhost:5000
AZURE_DEVOPS_DEFAULT_PROJECT matches exact project nameappsettings.json has the required Azure DevOps configurationdocker compose logsdotnet --versiondotnet restoreappsettings.json has the correct Azure DevOps settingsmcp-azure-devops/
├── src/
│ ├── Viamus.Azure.Devops.Mcp.Core/
│ │ ├── Configuration/ # Shared Azure DevOps options and safe validation
│ │ ├── Errors/ # Error classification and MCP tool error handling
│ │ ├── Models/ # Shared DTOs
│ │ ├── Services/ # Azure DevOps SDK integration
│ │ └── Tools/ # Work Items, Git, PRs, builds, Wiki
│ ├── Viamus.Azure.Devops.Mcp.Server/
│ │ ├── Configuration/ # HTTP security options
│ │ ├── Middleware/ # API key authentication
│ │ ├── Program.cs # HTTP entry point
│ │ ├── appsettings.json
│ │ └── Dockerfile
│ └── Viamus.Azure.Devops.Mcp.Stdio/
│ ├── Program.cs # STDIO entry point
│ ├── StdioHost.cs # Host setup, executable-relative config, stderr logs
│ └── appsettings.json
├── tests/
│ ├── Viamus.Azure.Devops.Mcp.Server.Tests/
│ │ ├── Configuration/
│ │ ├── Errors/
│ │ ├── Middleware/
│ │ ├── Models/
│ │ ├── Services/
│ │ ├── Tools/
│ │ └── Transport/ # Local HTTP/STDIO protocol integration tests
│ └── Viamus.Azure.Devops.Mcp.Stdio.Tests/
│ ├── StdioHostTests.cs
│ └── StdioProtocolTests.cs
├── docs/stdio-and-error-handling.md
├── .github/
├── .env.example
├── docker-compose.yml
├── install-mcp-azure-devops.ps1
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── SECURITY.md
└── LICENSE
Complete work item details including all standard fields and custom fields.
Lightweight representation with essential fields (Id, Title, Type, State, Priority) for list views.
Represents a comment on a work item with author and timestamp.
Repository details including Id, Name, DefaultBranch, URLs, Size, and project information.
Branch information including Name, ObjectId (commit), and creator details.
Represents a file or folder in a repository with Path, ObjectId, GitObjectType, and IsFolder flag.
File content with Path, Content (text), IsBinary flag, Encoding, and Size.
Complete pull request details including:
Reviewer information including DisplayName, Vote (-10 to 10), IsRequired, and HasDeclined status.
Comment thread with Id, Status (Active, Fixed, etc.), FilePath, LineNumber, EndLineNumber, and Comments list.
Individual comment with Id, Content, Author, timestamps, and CommentType.
Pipeline (build definition) details including Id, Name, Folder, ConfigurationType, and QueueStatus.
Comprehensive build information including:
Build log metadata with Id, Type, Url, LineCount, and timestamps.
Timeline record (stage, job, or task) with Id, ParentId, Type, Name, State, Result, timing information, and error/warning counts.
# Run all tests
dotnet test
# Run specific test class
dotnet test --filter "FullyQualifiedName~WorkItemToolsTests"
# Run with coverage
dotnet test --collect:"XPlat Code Coverage"
# Debug build
dotnet build
# Release build
dotnet build -c Release
We welcome contributions! Please see CONTRIBUTING.md for:
This project is licensed under the MIT License.
Azure DevOps MCP for querying repositories, pipelines, work items, and delivery metadata via HTTP
工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式,而不是 PlugMCP 代理伺服器。
這筆記錄未列出必要的環境變數。
MCP Azure Devops 透過 stdio 在本機執行。
上次檢查時間:2026-10-27。 Azure DevOps MCP for querying repositories, pipelines, work items, and delivery metadata via HTTP