Getting Started with Azure DevOps MCP Server

This guide will help you set up and configure the Azure DevOps MCP Server for your development workflow.

Prerequisites

Step 1: Generate Azure DevOps Personal Access Token

1. Sign in to your Azure DevOps organization at https://dev.azure.com/{your-organization}

2. Access Token Settings:
   • Click your profile icon (top right)
   • Select Personal access tokens
3. Create New Token:
   • Click + New Token
   • Name: MCP Server Access (or your preferred name)
   • Organization: Select your target organization
   • Expiration: Set according to your security policy

4. Configure Permissions:

   Read-Only Access (Recommended)

   • ✅ Code: Read
   • ✅ Work Items: Read
   • ✅ Project and Team: Read
   • ✅ Test Management: Read

   Write Operations (Optional)

   • ✅ Code: Read & Write (for PR comments)
   • ✅ Work Items: Read & Write (for tag updates)
   • ✅ Pull Request: Read & Write (for creating drafts)
5. Save Token: Copy and securely store your token (you won’t see it again!)

Step 2: Choose Your Setup Method

Option A: Docker (Recommended)

Perfect for production use and easy setup:

# Pull the latest image
docker pull ghcr.io/decriptor/azuredevops-mcp:latest

# Run with your configuration
docker run -it \
  -e AzureDevOps__OrganizationUrl="https://dev.azure.com/your-organization" \
  -e AzureDevOps__PersonalAccessToken="your-pat-goes-here" \
  ghcr.io/decriptor/azuredevops-mcp:latest

Option B: Development Containers (VS Code)

For development and contributing:

1. Install VS Code and Dev Containers extension
2. Clone the repository:

   git clone https://github.com/decriptor/AzureDevOps.MCP.git
   cd AzureDevOps.MCP
   

3. Open in VS Code and click “Reopen in Container”
4. Everything is pre-configured with .NET 9, tools, and extensions!

Option C: Local Development

For local .NET development:

# Clone the repository
git clone https://github.com/decriptor/AzureDevOps.MCP.git
cd AzureDevOps.MCP

# Set environment variables
export AzureDevOps__OrganizationUrl="https://dev.azure.com/your-organization"
export AzureDevOps__PersonalAccessToken="your-pat-goes-here"

# Build and run
dotnet restore
dotnet build
dotnet run --project src/AzureDevOps.MCP

Step 3: Integrate with MCP Clients

Claude Desktop Integration

Add to your Claude Desktop configuration file:

Location:

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

Configuration:

{
  "mcpServers": {
    "azure-devops": {
      "command": "docker",
      "args": [
        "run", "-i",
        "-e", "AzureDevOps__OrganizationUrl=https://dev.azure.com/your-organization",
        "-e", "AzureDevOps__PersonalAccessToken=your-pat-goes-here",
        "ghcr.io/decriptor/azuredevops-mcp:latest"
      ]
    }
  }
}

VS Code Extension Integration

For VS Code MCP extensions, use the stdio transport:

{
  "mcp.servers": {
    "azure-devops": {
      "command": "docker",
      "args": ["run", "-i", "ghcr.io/decriptor/azuredevops-mcp:latest"],
      "env": {
        "AzureDevOps__OrganizationUrl": "https://dev.azure.com/your-organization",
        "AzureDevOps__PersonalAccessToken": "your-pat-goes-here"
      }
    }
  }
}

Step 4: Verify Installation

Once configured, test the connection:

1. In Claude Desktop: Ask “List my Azure DevOps projects”
2. Expected Response: You should see your accessible projects
3. Try More Commands:
   • “Show repositories in [project-name]”
   • “Get work items for [project-name]”
   • “Show recent builds for [project-name]”

Configuration Options

Environment Variables

Production Configuration

For production deployments, use appsettings.Production.json:

{
  "AzureDevOps": {
    "OrganizationUrl": "https://dev.azure.com/your-organization",
    "EnabledWriteOperations": ["PullRequestComments"],
    "RequireConfirmation": true,
    "EnableAuditLogging": true
  },
  "Caching": {
    "EnableMemoryCache": true,
    "MaxMemoryCacheSizeMB": 100,
    "DefaultCacheDurationMinutes": 15
  },
  "Performance": {
    "SlowOperationThresholdMs": 1000,
    "EnableCircuitBreaker": true
  },
  "Security": {
    "EnableKeyVault": true,
    "KeyVaultUrl": "https://your-keyvault.vault.azure.net/"
  }
}

Enabling Write Operations

By default, all write operations are disabled for safety. To enable specific operations:

{
  "AzureDevOps": {
    "EnabledWriteOperations": [
      "PullRequestComments",
      "CreateDraftPullRequest",
      "UpdateWorkItemTags"
    ],
    "RequireConfirmation": true,
    "EnableAuditLogging": true
  }
}

Available Write Operations

• PullRequestComments: Add comments to pull requests
• CreateDraftPullRequest: Create draft PRs (not published until ready)
• UpdateWorkItemTags: Add or remove tags from work items
• WorkItemComments: Add comments to work items

Write Operation Safety

1. Opt-In Required: Must explicitly enable each operation type
2. Confirmation Required: Operations require confirm: true parameter
3. Audit Logging: All write operations are logged with full context
4. Preview Mode: See what will change before confirmation

Troubleshooting

Common Issues

“Authentication failed”

• Verify your PAT token has correct permissions
• Check if token has expired
• Ensure organization URL is correct

“No projects found”

• Verify PAT has “Project and Team: Read” permission
• Check if you have access to any projects in the organization

“Docker: permission denied”

• On Linux/macOS: Add user to docker group or use sudo
• On Windows: Ensure Docker Desktop is running

“MCP server not responding”

• Check Docker container logs: docker logs [container-id]
• Verify environment variables are set correctly
• Ensure no firewall blocking stdio communication

Getting Help

• 📚 API Reference - Complete tool documentation
• 💡 Examples - Common usage patterns
• 🐛 Report Issues - Bug reports and feature requests
• 💬 Discussions - Community support

Next Steps

Now that you have the server running:

1. Explore the API Reference - Learn about all available tools
2. Check out Examples - See common workflows and patterns
3. Configure Write Operations - Enable safe write capabilities for your team
4. Set up Monitoring - Configure performance monitoring and alerts
5. Contribute - Help improve the project on GitHub