Azure DevOps MCP

Prerequisites

Docker

curl http://localhost:8080/health

Automated Installation (Windows)

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

```powershell

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:

---

Pipeline/Build Tools

---

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

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):

#### How It Works

- When `RequireApiKey` is `false` (default): No authentication required
- When `RequireApiKey` is `true`: All requests (except `/health`) require a valid API key
- The `/health` endpoint is always accessible without authentication

#### Providing the API Key

Clients can provide the API key one way:

**Option 1 - X-API-Key Header (recommended):**

#### Generating a Secure API Key

Pipelines and Builds

• "List all pipelines in the project"
• "Show me the recent builds for pipeline 'CI-Build'"
• "What's the status of build #789?"
• "Show me failed builds from the last week"
• "Get the logs for build #456"
• "Show me the timeline of build #123"
• "What builds are currently in progress?"

---

Pipeline/Build DTOs

#### PipelineDto Pipeline (build definition) details including Id, Name, Folder, ConfigurationType, and QueueStatus.

#### BuildDto Comprehensive build information including: - Id, BuildNumber, Status, Result - SourceBranch, SourceVersion - RequestedBy, RequestedFor - QueueTime, StartTime, FinishTime - Definition details, LogsUrl, Reason, Priority

#### BuildLogDto Build log metadata with Id, Type, Url, LineCount, and timestamps.

#### BuildTimelineRecordDto Timeline record (stage, job, or task) with Id, ParentId, Type, Name, State, Result, timing information, and error/warning counts.

---

Building

```bash

Debug build

dotnet build

Release build

dotnet build -c Release ```

Quick Start

Get up and running in 3 steps:

Usage Examples

After configuring the MCP client, you can ask questions like:

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):

```bash 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:

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

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

Running Options

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

```bash

Client Configuration

API Key Authentication

The server supports optional API key authentication to protect your MCP endpoints.

Configuration

Add to appsettings.json:

{
  "ServerSecurity": {
    "ApiKey": "your-secret-api-key",
    "RequireApiKey": true
  }
}

Or via environment variables: ```bash

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 ``` </details>

<details> <summary><strong>Project not found</strong></summary>

1. Verify AZURE_DEVOPS_DEFAULT_PROJECT matches exact project name 2. Or pass the project name explicitly in your queries 3. Check the selected organization's PAT has access to the project </details>

<details> <summary><strong>Docker: Container exits immediately</strong></summary>

1. Check if appsettings.json has the required Azure DevOps configuration 2. View logs: docker compose logs 3. Ensure port 8080 is not in use by another application </details>

<details> <summary><strong>.NET CLI: dotnet run fails</strong></summary>

1. Verify .NET 10 SDK is installed: dotnet --version 2. Restore packages: dotnet restore 3. Check if appsettings.json has the correct Azure DevOps settings </details>

---

API Reference

Troubleshooting