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.

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

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"
  }
}

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

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"

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 (HTTP transport)

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

Git Repository Tools

Pull Request Tools

Pipeline/Build Tools

Prerequisites

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:

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

Running Options

Option 1: Docker Compose (Recommended)

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

docker compose up -d

Server URL: http://localhost:8080

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

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/Viamus.Azure.Devops.Mcp.Server -c Release -r linux-x64 -o ./publish/linux-x64

# macOS (Intel)
dotnet publish src/Viamus.Azure.Devops.Mcp.Server -c Release -r osx-x64 -o ./publish/osx-x64

# macOS (Apple Silicon)
dotnet publish src/Viamus.Azure.Devops.Mcp.Server -c Release -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

Client Configuration

Claude Desktop

Option A - Using CLI (recommended):

claude mcp add azure-devops --transport http http://localhost:8080

Option B - Manual configuration:

Edit claude_desktop_config.json:

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

{
  "mcpServers": {
    "azure-devops": {
      "url": "http://localhost:8080"
    }
  }
}

Claude Code

Run from your project directory:

claude mcp add azure-devops --transport http http://localhost:8080

Or add manually to .claude/settings.json:

{
  "mcpServers": {
    "azure-devops": {
      "type": "http",
      "url": "http://localhost:8080"
    }
  }
}

Note: Use port 5000 if running with .NET CLI, or 8080 if running with Docker.

Usage Examples

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

Work Items

• "List the active work items in project X"
• "What bugs are assigned to me?"
• "Show me the details of work item #1234"
• "What work items were changed in the last 7 days?"
• "Search for work items with 'login' in the title"
• "Add a comment to work item #1234 saying the bug was fixed"

Git Repositories

• "List all repositories in project X"
• "Show me the branches in the 'my-app' repository"
• "What files are in the /src folder of the 'backend' repository?"
• "Get the content of the README.md file from the 'frontend' repository"
• "Search for all .cs files in the 'api' repository"
• "Show me the content of /src/Program.cs from the 'main' branch"

Pull Requests

• "Show me all active pull requests in the 'my-repo' repository"
• "Get details of pull request #123"
• "What comments are on PR #456?"
• "Search for pull requests related to 'authentication'"
• "Show me PRs targeting the 'main' branch"
• "List PRs created by user@email.com"

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?"

Troubleshooting

Common Issues

Project Structure

mcp-azure-devops/
├── src/
│   └── Viamus.Azure.Devops.Mcp.Server/
│       ├── Configuration/      # App configuration classes
│       ├── Models/             # DTOs and data models
│       ├── Services/           # Azure DevOps SDK integration
│       ├── Tools/              # MCP tool implementations
│       ├── Program.cs          # Entry point
│       ├── appsettings.json    # App settings
│       └── Dockerfile          # Container definition
├── tests/
│   └── Viamus.Azure.Devops.Mcp.Server.Tests/
│       ├── Models/             # DTO tests
│       └── Tools/              # Tool behavior tests
├── .github/                    # GitHub templates
├── .env.example                # Environment template (Docker)
├── docker-compose.yml          # Docker orchestration
├── CONTRIBUTING.md             # Contributor guide
├── CODE_OF_CONDUCT.md          # Community guidelines
├── SECURITY.md                 # Security policy
└── LICENSE                     # MIT License

API Reference

Work Item DTOs

WorkItemDto

Complete work item details including all standard fields and custom fields.

WorkItemSummaryDto

Lightweight representation with essential fields (Id, Title, Type, State, Priority) for list views.

WorkItemCommentDto

Represents a comment on a work item with author and timestamp.

Git DTOs

RepositoryDto

Repository details including Id, Name, DefaultBranch, URLs, Size, and project information.

BranchDto

Branch information including Name, ObjectId (commit), and creator details.

GitItemDto

Represents a file or folder in a repository with Path, ObjectId, GitObjectType, and IsFolder flag.

GitFileContentDto

File content with Path, Content (text), IsBinary flag, Encoding, and Size.

Pull Request DTOs

PullRequestDto

Complete pull request details including:

• PullRequestId, Title, Description
• SourceBranch, TargetBranch
• Status (Active, Abandoned, Completed)
• CreatedBy, CreationDate, ClosedDate
• Reviewers list, MergeStatus, IsDraft
• Repository and Project information

PullRequestReviewerDto

Reviewer information including DisplayName, Vote (-10 to 10), IsRequired, and HasDeclined status.

PullRequestThreadDto

Comment thread with Id, Status (Active, Fixed, etc.), FilePath, LineNumber, and Comments list.

PullRequestCommentDto

Individual comment with Id, Content, Author, timestamps, and CommentType.

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.

Development

Running Tests

# Run all tests
dotnet test

# Run specific test class
dotnet test --filter "FullyQualifiedName~WorkItemToolsTests"

# Run with coverage
dotnet test --collect:"XPlat Code Coverage"

Building

# Debug build
dotnet build

# Release build
dotnet build -c Release

Contributing

We welcome contributions! Please see CONTRIBUTING.md for:

• Development setup
• Coding standards
• How to add new MCP tools
• Pull request guidelines

License

This project is licensed under the MIT License.

Links

• Model Context Protocol
• Azure DevOps REST API
• Report an Issue