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

State-Based Queries

Advanced Filtering

Custom WIQL Queries

Work Item Modification

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

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:

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