Azure DevOps MCP Server

This is a Model Context Protocol (MCP) server that provides access to Azure DevOps resources and tools through a standardized interface.

Features

The server provides the following Azure DevOps tools:

• get_workitems - Retrieve work items using WIQL queries
• get_repositories - List Git repositories
• get_pullrequests - Get pull requests from repositories
• get_builds - Retrieve build pipeline information
• get_commits - Get Git commits from repositories
• create_workitem - Create new work items (bugs, features, tasks, etc.)

Prerequisites

1. Azure DevOps Account: You need access to an Azure DevOps organization
2. Personal Access Token: Generate a PAT with the following scopes:
   • Work Items (Read & Write)
   • Code (Read)
   • Build (Read)
   • Release (Read)

Setup Instructions

1. Configure Environment Variables

Edit the .env file in the project root and replace the placeholder values:

# Your Azure DevOps organization name (e.g., "mycompany" for dev.azure.com/mycompany)
AZURE_DEVOPS_ORG=your-actual-organization

# Your Azure DevOps project name
AZURE_DEVOPS_PROJECT=your-actual-project

# Your Azure DevOps Personal Access Token
AZURE_DEVOPS_TOKEN=your-actual-personal-access-token

2. Generate Personal Access Token

1. Go to your Azure DevOps organization: https://dev.azure.com/{your-org}/_usersSettings/tokens
2. Click "New Token"
3. Set the following scopes:
   • Work Items: Read & Write
   • Code: Read
   • Build: Read
   • Release: Read
4. Copy the generated token and add it to your .env file

3. Test the Server

Run the server to test your configuration:

# Activate virtual environment
source azure-mcp-venv/bin/activate

# Run the server
python main.py

If successful, you should see: 🚀 Azure DevOps MCP Server running...

Running the MCP Server

Option 1: Terminal Interactive Client (Recommended for VPN environments)

If you're behind a VPN or can't connect through VS Code, you can use the interactive MCP client directly from the terminal:

# Navigate to the project directory
cd /Users/kshitijijari/Desktop/MySpace/MCP/azure-devops-mcp-server

# Activate the virtual environment
source azure-mcp-venv/bin/activate

# Run the interactive MCP client
python mcp_client.py

This will start an interactive menu with the following options:

1. List available tools - See all Azure DevOps tools available
2. Get work items - Run custom WIQL queries
3. Get repositories - List Git repositories
4. Get builds - View build pipeline information
5. Get pull requests - View PRs from repositories
6. Get commits - View Git commits
7. Create work item - Create new work items
8. Exit

Option 2: Direct MCP Server

Run the MCP server directly (for use with MCP clients):

# Navigate to the project directory
cd /Users/kshitijijari/Desktop/MySpace/MCP/azure-devops-mcp-server

# Activate the virtual environment
source azure-mcp-venv/bin/activate

# Run the MCP server
python main.py

Option 3: Using the startup script

# Make the script executable
chmod +x start_mcp_server.sh

# Run the startup script
./start_mcp_server.sh

Adding to MCP Client (VS Code/Cursor)

Option 1: Using the provided configuration

Copy the mcp_config.json file to your MCP client configuration directory and update the environment variables:

{
  "mcpServers": {
    "azure-devops": {
      "command": "python",
      "args": [
        "/Users/kshitijijari/Desktop/MySpace/MCP/azure-devops-mcp-server/main.py"
      ],
      "env": {
        "AZURE_DEVOPS_ORG": "your-actual-organization",
        "AZURE_DEVOPS_PROJECT": "your-actual-project",
        "AZURE_DEVOPS_TOKEN": "your-actual-personal-access-token"
      }
    }
  }
}

Option 2: Manual configuration

Add this to your MCP client configuration:

{
  "mcpServers": {
    "azure-devops": {
      "command": "python",
      "args": ["/absolute/path/to/your/azure-devops-mcp-server/main.py"],
      "env": {
        "AZURE_DEVOPS_ORG": "your-organization",
        "AZURE_DEVOPS_PROJECT": "your-project",
        "AZURE_DEVOPS_TOKEN": "your-personal-access-token"
      }
    }
  }
}

Option 3: Using the startup script

You can also use the provided startup script:

{
  "mcpServers": {
    "azure-devops": {
      "command": "/Users/kshitijijari/Desktop/MySpace/MCP/azure-devops-mcp-server/start_mcp_server.sh",
      "env": {
        "AZURE_DEVOPS_ORG": "your-organization",
        "AZURE_DEVOPS_PROJECT": "your-project",
        "AZURE_DEVOPS_TOKEN": "your-personal-access-token"
      }
    }
  }
}

Usage Examples

Terminal Interactive Client Examples

When using the interactive MCP client (python mcp_client.py), you can:

Get work items with custom queries:

• Enter a WIQL query like: SELECT [System.Id], [System.Title], [System.State] FROM WorkItems WHERE [System.AssignedTo] = 'John Doe'
• Or use the default query for recent work items

Get repositories:

• Optionally filter by repository name
• View all available Git repositories

Get builds:

• Filter by build definition ID
• Filter by status (inProgress, completed, all)
• Set custom limits

Create work items:

• Choose work item type (Bug, Feature, Task, User Story, Epic)
• Set title, description, assignee, area path, and iteration path

MCP Client Integration Examples

Once configured, you can use the Azure DevOps tools in your MCP client:

Get Work Items

{
  "name": "get_workitems",
  "arguments": {
    "query": "SELECT [System.Id], [System.Title], [System.State] FROM WorkItems WHERE [System.TeamProject] = @project",
    "limit": 10
  }
}

Get Repositories

{
  "name": "get_repositories",
  "arguments": {}
}

Create Work Item

{
  "name": "create_workitem",
  "arguments": {
    "work_item_type": "Bug",
    "title": "New bug report",
    "description": "Description of the bug",
    "assigned_to": "user@example.com"
  }
}

Troubleshooting

Common Issues

1. Authentication Error: Verify your Personal Access Token is correct and has the required scopes
2. Organization/Project Not Found: Check that your organization and project names are spelled correctly
3. Permission Denied: Ensure your PAT has the necessary permissions for the operations you're trying to perform

Debug Mode

To enable debug logging, modify the logging level in main.py:

logging.basicConfig(level=logging.DEBUG)

Security Notes

• Never commit your .env file or Personal Access Token to version control
• Use environment variables or secure configuration management in production
• Regularly rotate your Personal Access Tokens
• Use the principle of least privilege when setting token scopes

Support

For issues or questions:

1. Check the Azure DevOps API documentation
2. Verify your token permissions
3. Test your connection using the Azure DevOps REST API directly