Azure DevOps MCP Server

A Model Context Protocol (MCP) server that provides seamless integration with Azure DevOps, allowing you to read backlogs, work items, and perform various queries through a standardized interface.

Features

• Comprehensive Work Item Management: Query work items by ID, type, state, assignee, and more
• Backlog Integration: Access team backlogs and sprint planning items
• Flexible State Filtering: Filter work items by specific states or state categories (active, completed, review)
• WIQL Query Support: Execute custom Work Item Query Language queries
• Smart Defaults: Configurable default search parameters for streamlined workflows
• Advanced Filtering: Support for iteration paths, area paths, and complex multi-condition queries

Installation

Prerequisites

• Python 3.11 or higher
• Azure DevOps Personal Access Token (PAT)
• Access to an Azure DevOps organization and project

Setup

1. Clone the repository:

   git clone https://github.com/jhlia0/azure-devops-mcp.git
   cd mcp-server-azure-devops
   

2. Install dependencies:

   uv sync
   

3. Configure environment variables:

   cp .env.example .env
   

   Edit the .env file with your Azure DevOps credentials. It's highly recommended to set DEFAULT_USER if you plan to query your own work items:

   ORGANIZATION=your-organization
   PROJECT=your-project
   AZURE_DEVOPS_PAT=your-personal-access-token
   DEFAULT_USER=your-email@example.com # (Optional) Recommended for personal work item queries
   

4. Run the server:

   python main.py
   

Configuration

Required Environment Variables

Optional Configuration

Available MCP Tools

Core Work Item Tools

• get_work_items - Get work items by their IDs
• get_work_items_by_query - Execute custom WIQL queries with optional project filtering
• get_work_items_by_type - Get work items by type (Bug, Task, etc.) with optional state and project filtering
• get_work_items_by_state - Get work items by specific state with additional filters and optional project filtering
• get_work_items_with_filters - Advanced filtering with multiple criteria and optional project filtering

User-Focused Tools

• get_my_work_items - Get work items assigned to a specific user with state and optional project filtering
• get_active_work_items - Get all active work items using default filters and optional project filtering

Backlog Tools

• get_backlog_items - Get backlog items for a team with optional project filtering
• get_default_backlog - Get backlog items using default team settings with optional project filtering

State Management Tools

• get_work_items_by_state_category - Get work items by state category (active, completed, review) with optional project filtering
• get_closed_work_items - Get closed work items with optional filters and project filtering
• get_available_states - Get list of common work item states

Work Item Modification Tools

• update_work_item_title - Update the title of a work item
• update_work_item_description - Update the description of a work item
• add_work_item_comment - Add a comment to a work item
• create_work_item - Create a new work item

Utility Tools

• get_default_work_items - Get work items using all default search settings with optional project filtering
• get_project_info - Get project configuration and default settings

Usage Examples

Basic Queries

# Get specific work items by ID
get_work_items({"ids": [1234, 5678]})

# Get all active work items
get_active_work_items()

# Get work items assigned to current user
get_my_work_items()

State-Based Queries

# Get work items in specific states
get_my_work_items(states=["Active", "In Progress"])

# Get work items by state category
get_work_items_by_state_category("active")

# Get bugs in specific state
get_work_items_by_type("Bug", states=["New", "Active"])

Advanced Filtering

# Complex multi-condition query
get_work_items_with_filters({
    "states": ["New", "Active"],
    "work_item_types": ["Bug", "Task"],
    "assigned_to": "user@example.com",
    "max_results": 50
})

# Get work items by specific state with filters
get_work_items_by_state({
    "state": "In Progress",
    "work_item_type": "User Story",
    "assigned_to": "developer@company.com"
})

Custom WIQL Queries

# Execute custom WIQL query
get_work_items_by_query({
    "wiql": """
    SELECT [System.Id], [System.Title], [System.State]
    FROM WorkItems
    WHERE [System.WorkItemType] = 'Bug'
    AND [System.State] = 'Active'
    ORDER BY [System.CreatedDate] DESC
    """
})

# Execute custom WIQL query with project filter
get_work_items_by_query({
    "wiql": "SELECT [System.Id] FROM WorkItems WHERE [System.WorkItemType] = 'Bug'",
    "project": "MyProject",
    "include_project_filter": True
})

Work Item Modification

# Update work item title
update_work_item_title({"id": 1234, "title": "New Title for Work Item"})

# Update work item description
update_work_item_description({"id": 1234, "description": "Updated description text."})

# Add a comment to a work item
add_work_item_comment({"id": 1234, "comment": "This is a new comment."})

# Create a new bug
create_work_item({
    "work_item_type": "Bug",
    "title": "New Bug Found",
    "description": "This is a description of the new bug.",
    "assigned_to": "user@example.com",
    "area_path": "MyProject\Area\SubArea"
})

Authentication

The server uses Azure DevOps Personal Access Tokens (PAT) for authentication. To create a PAT:

1. Go to https://dev.azure.com/{organization}/_usersSettings/tokens
2. Click "New Token"
3. Configure the token with appropriate permissions:
   • Work Items: Read
   • Project and Team: Read
4. Copy the generated token and add it to your .env file

Architecture

Key Components

• Configuration Layer (config.py): Manages environment variables and default settings using Pydantic
• Client Layer (azure_devops_client.py): Handles Azure DevOps REST API communication
• Server Layer (server.py): Implements MCP tools and request handling
• Entry Point (main.py): Starts the FastMCP server

Development

Adding New Tools

1. Define request models in server.py
2. Implement the tool function with @mcp.tool() decorator
3. Add appropriate error handling and response formatting
4. Update this README with the new tool documentation

Testing

# Install development dependencies
uv sync

# Run the server in development mode
python main.py

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Troubleshooting

Common Issues

1. Authentication Errors: Verify your PAT has the correct permissions and hasn't expired
2. Project Not Found: Check that the organization and project names are correct
3. Network Issues: Ensure you can access Azure DevOps from your network
4. State Filtering: Different projects may use different state names - check your project's work item states

Debugging

Enable debug logging by setting the environment variable:

export DEBUG=true
python main.py

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues and questions:

• Check the troubleshooting section above
• Review Azure DevOps REST API documentation
• Open an issue in the project repository

Related Projects

• FastMCP - The MCP framework used by this server
• Azure DevOps REST API - Official API documentation