Azure DevOps MCP Server

A Model Context Protocol (MCP) server that integrates Azure DevOps with VS Code/GitHub Copilot and other MCP-compatible clients. This server allows you to fetch work item details and update work item statuses directly from your AI assistant.

Features

• Get Work Item Details: Fetch comprehensive information about any work item including:

  • Title, type, state, and assigned user
  • Description and steps to reproduce (for bugs)
  • All comments with authors and timestamps
  • Metadata (creation date, last modified, area path, iteration, tags)

• Update Work Item Status: Change the state/status of work items (e.g., from "New" to "Active", "Resolved" to "Closed")

Prerequisites

• Python 3.10 or higher
• An Azure DevOps account with access to a project
• A Personal Access Token (PAT) with Work Items Read & Write permissions

Installation

Option 1: Install from GitHub (Easiest for Users)

pip install git+https://github.com/Akshay-Quorum2145/ADO-MCP.git

MCP Config (without venv):

{
  "servers": {
    "ado": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "ado_mcp.server"],
      "env": {
        "ADO_ORGANIZATION": "your-org",
        "ADO_PROJECT": "your-project",
        "ADO_PAT": "your-pat"
      }
    }
  }
}

MCP Config (with venv):

{
  "servers": {
    "ado": {
      "type": "stdio",
      "command": "C:\\path\\to\\venv\\Scripts\\python.exe",
      "args": ["-m", "ado_mcp.server"],
      "env": {
        "ADO_ORGANIZATION": "your-org",
        "ADO_PROJECT": "your-project",
        "ADO_PAT": "your-pat"
      }
    }
  }
}

Option 2: Clone for Development

1. Clone or download this repository

2. Install the package:

   pip install -e .
   

   Or for development with optional dependencies:

   pip install -e ".[dev]"
   

Configuration

Step 1: Create a Personal Access Token (PAT)

1. Go to your Azure DevOps organization: https://dev.azure.com/[your-organization]
2. Click on your profile icon (top right) → Personal access tokens
3. Click + New Token
4. Configure the token:
   • Name: Give it a descriptive name (e.g., "MCP Server Access")
   • Organization: Select your organization
   • Expiration: Set an appropriate expiration date
   • Scopes: Select Custom defined and check:
     • Work Items: Read, Write
5. Click Create
6. IMPORTANT: Copy the token immediately (you won't be able to see it again)

Step 2: Configure VS Code / GitHub Copilot

Create an MCP configuration file in your workspace or global settings:

Create .vscode/mcp.json or your MCP config location:

Without venv:

{
  "servers": {
    "ado": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "ado_mcp.server"],
      "env": {
        "ADO_ORGANIZATION": "your-organization-name",
        "ADO_PROJECT": "your-project-name",
        "ADO_PAT": "your-personal-access-token"
      }
    }
  }
}

With venv (use full Python path):

{
  "servers": {
    "ado": {
      "type": "stdio",
      "command": "C:\\path\\to\\venv\\Scripts\\python.exe",
      "args": ["-m", "ado_mcp.server"],
      "env": {
        "ADO_ORGANIZATION": "your-organization-name",
        "ADO_PROJECT": "your-project-name",
        "ADO_PAT": "your-personal-access-token"
      }
    }
  }
}

Restart VS Code.

Usage

Once configured, you can interact with Azure DevOps through GitHub Copilot Chat or any MCP-compatible client:

Get Work Item Details

Get details for work item 12345

or

Show me information about ADO work item 12345

Update Work Item Status

Change work item 12345 status to Active

or

Update the state of work item 12345 to Resolved

Available Tools

get_work_item

Retrieves detailed information about a work item.

Parameters:

• work_item_id (integer, required): The ID of the work item

Returns:

• Complete work item details including description, comments, status, and metadata

update_work_item_status

Updates the state/status of a work item.

Parameters:

• work_item_id (integer, required): The ID of the work item
• new_state (string, required): The new state (e.g., "Active", "Resolved", "Closed")

Returns:

• Confirmation with updated work item details

Note: Available states depend on your work item type and process template (Agile, Scrum, CMMI, etc.). Common states include:

• New, Active, Resolved, Closed, Removed (for Bugs)
• New, Active, Closed, Removed (for Tasks)
• New, Active, Resolved, Closed, Removed (for User Stories)

Troubleshooting

Authentication Issues

• Error: "Missing required environment variables"

  • Ensure your .env file exists and contains all three required variables
  • Check that the MCP settings correctly reference the environment variables or .env file location

• Error: "Failed to initialize Azure DevOps client"

  • Verify your PAT is valid and hasn't expired
  • Ensure your PAT has Work Items Read & Write permissions
  • Check that your organization and project names are correct

Work Item Issues

• Error: "Failed to get work item"

  • Verify the work item ID exists in your project
  • Ensure you have permission to view the work item
  • Check that you're connected to the correct project

• Error: "Failed to update work item state"

  • Verify the new state is valid for the work item type
  • Ensure the state transition is allowed (some transitions may be restricted by workflow rules)
  • Check that you have permission to edit the work item

Development

To contribute or modify the server:

1. Install development dependencies:

   pip install -e ".[dev]"
   

2. Run tests (when available):

   pytest
   

3. Format code:

   black src/
   

Security Notes

• Never commit your .env file or expose your PAT
• The .gitignore file is configured to exclude .env files
• Consider using short-lived PATs and rotating them regularly
• Use the minimum required scopes for your PAT (Read & Write for Work Items)

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.