Azure DevOps MCP Server

A Model Context Protocol (MCP) server that provides tools for interacting with Azure DevOps. This server enables AI assistants to manage work items, repositories, branches, commits, and more.

Features

• Work Items: Query, create, update, delete work items, comments, linking, attachments, and cycle time tracking
• Git Repositories: List repos, branches, commits, and file contents
• Pull Requests: Full PR lifecycle, reviewers, comments, merging
• Pipelines & Builds: List, run, cancel pipelines and builds, view logs
• Releases: Release definitions, deployments, approvals
• Boards: Kanban boards, columns, swimlanes, card movement
• Wiki: Create, update, delete wiki pages
• Test Plans: Test plans, suites, cases, runs, and results
• Artifacts: Package feeds and packages
• Project & Teams: Projects, teams, iterations, area paths
• Users & Notifications: User search, notification subscriptions
• Dashboards & Policies: Dashboard management, branch policies

Transport Modes

The server supports two transport modes:

Prerequisites

• Node.js 18 or higher
• An Azure DevOps organization
• A Personal Access Token (PAT) with appropriate permissions

Installation

npm install
npm run build

Configuration

Environment Variables

Generating a Personal Access Token

1. Go to Azure DevOps → User Settings → Personal Access Tokens
2. Click “New Token”
3. Configure the following scopes:
   • Work Items: Read & Write
   • Code: Read & Write
   • Build: Read & Execute
   • Release: Read, Write & Execute
   • Test Management: Read & Write
   • Wiki: Read & Write
   • Packaging: Read
   • Project and Team: Read
   • Service Connections: Read
   • Variable Groups: Read
   • Dashboard: Read
4. Copy the generated token

Claude Desktop Configuration

Add to your claude_desktop_config.json (typically located at %APPDATA%\Claude\claude_desktop_config.json on Windows or ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "azure-devops": {
      "command": "node",
      "args": ["C:/path/to/azure-devops-mcp/dist/index.js"],
      "env": {
        "ADO_PAT": "your-pat-token",
        "ADO_ORG_URL": "https://dev.azure.com/your-org",
        "ADO_PROJECT": "your-default-project"
      }
    }
  }
}

VS Code with GitHub Copilot Configuration

To use this MCP server with GitHub Copilot in VS Code:

1. Enable MCP support in VS Code (requires GitHub Copilot Chat extension):

   • Open VS Code Settings (Ctrl+, or Cmd+,)
   • Search for “mcp”
   • Enable GitHub > Copilot > Chat > MCP: Enabled

2. Configure the MCP server by adding to your VS Code settings.json:

{
  "github.copilot.chat.mcp.servers": {
    "azure-devops": {
      "command": "node",
      "args": ["C:/path/to/azure-devops-mcp/dist/index.js"],
      "env": {
        "ADO_PAT": "your-pat-token",
        "ADO_ORG_URL": "https://dev.azure.com/your-org",
        "ADO_PROJECT": "your-default-project"
      }
    }
  }
}

Alternatively, create a .vscode/mcp.json file in your workspace:

{
  "servers": {
    "azure-devops": {
      "command": "node",
      "args": ["C:/path/to/azure-devops-mcp/dist/index.js"],
      "env": {
        "ADO_PAT": "your-pat-token",
        "ADO_ORG_URL": "https://dev.azure.com/your-org",
        "ADO_PROJECT": "your-default-project"
      }
    }
  }
}

3. Restart VS Code after configuration changes.

4. Use the tools in GitHub Copilot Chat by asking questions like:

   • “List all active bugs in Azure DevOps”
   • “Create a new task titled ‘Fix login bug’”
   • “Show me the branches in the main repository”

Note: MCP support in GitHub Copilot requires the latest version of the GitHub Copilot Chat extension. If you don’t see MCP settings, update your extension.

HTTP Mode

For web applications, remote clients, or when you want to run the server as a standalone service:

Quick Start:

# Set environment variables
export ADO_ORG_URL="https://dev.azure.com/your-org"
export ADO_PAT="your-pat-token"
export ADO_PROJECT="your-project"

# Start in HTTP mode
npm run start:http

Test the server:

# Health check
curl http://localhost:3000/health

# List tools
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

# Call a tool
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"list_projects","arguments":{}},"id":2}'

Docker:

# Build and run
docker-compose up -d

# Or build manually
docker build -t ado-mcp .
docker run -p 3000:3000 \
  -e ADO_ORG_URL="https://dev.azure.com/your-org" \
  -e ADO_PAT="your-pat-token" \
  ado-mcp

For detailed HTTP API documentation, see docs/HTTP_API.md.

Implementation Status

All tools are implemented, including type-specific work item tools beyond the original specification.

Total: 116 tools implemented

Available Tools

Work Items (Core)

Work Item Linking

Work Item Attachments

Git Repositories

Pull Requests

Boards

Projects & Teams

Pipelines

Builds (Classic)

Releases

Wiki

Test Plans

Artifacts

Service Connections

Variable Groups

Users

Notifications

Dashboards

Branch Policies

Example Usage

List Active Bugs (Simple)

Use list_bugs with:
- states: ["Active"]

List All Epics in a Sprint

Use list_epics with:
- iterationPath: "MyProject\\Sprint 1"
- states: ["New", "Active"]

Query Work Items with Flexible Filters

Use query_work_items with:
- workItemTypes: ["Bug", "Task"]
- states: ["Active"]
- assignedTo: "[email protected]"
- tags: ["priority-high"]

Query Active Bugs (Advanced WIQL)

Use list_work_items with query:
"SELECT [System.Id], [System.Title] FROM WorkItems WHERE [System.WorkItemType] = 'Bug' AND [System.State] = 'Active'"

Create a Task

Use create_work_item with:
- type: "Task"
- title: "Implement feature X"
- description: "Details about the task"
- assignedTo: "[email protected]"

List Repository Branches

Use list_branches with:
- repository: "my-repo"

Get Cycle Time Data

Work item get tools return firstActivatedDate (when work started) and cycleTimeDays (time from activation to close):

Use get_bug with:
- id: 123

Response includes:
- firstActivatedDate: "2024-01-15T10:00:00Z"
- cycleTimeDays: 5.5 (only for closed items)

For list tools, enable cycle time with includeActivatedDate (adds API calls per item):

Use list_bugs with:
- states: ["Closed"]
- includeActivatedDate: true

Development

# Install dependencies
npm install

# Build
npm run build

# Run in STDIO mode (for Claude Desktop, VS Code)
npm run start:stdio

# Run in HTTP mode (for web apps, remote clients)
npm run start:http

# Development mode (auto-rebuild)
npm run dev

# Development - HTTP mode with ts-node
npm run dev:http

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

Troubleshooting

Common PAT Issues

• 401 Unauthorized: PAT may be expired or invalid
• 403 Forbidden: PAT lacks required scope permissions
• 404 Not Found: Project or resource doesn’t exist, or PAT can’t access it

Connection Issues

1. Verify ADO_ORG_URL is correct (should be https://dev.azure.com/orgname)
2. Ensure PAT hasn’t expired
3. Check that PAT has access to the target project

License

MIT