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

Clone the repository:
git clone https://github.com/jhlia0/azure-devops-mcp.git cd mcp-server-azure-devops
Install dependencies:
uv sync
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
Run the server:
python main.py

Configuration

Required Environment Variables

Variable	Description	Example
`ORGANIZATION`	Azure DevOps organization name	`mycompany`
`PROJECT`	Azure DevOps project name	`MyProject`
`AZURE_DEVOPS_PAT`	Personal Access Token	`your-pat-token`

Optional Configuration

Variable	Default	Description
`DEFAULT_TEAM`	-	Default team name for backlog queries
`DEFAULT_USER`	-	Default user for work item queries (recommended for querying your own work items)
`DEFAULT_WORK_ITEM_TYPES`	`Bug,Task,User Story,Product Backlog Item`	Default work item types
`DEFAULT_MAX_RESULTS`	`100`	Maximum number of results to return
`EXCLUDE_CLOSED`	`true`	Exclude closed work items by default
`EXCLUDE_REMOVED`	`true`	Exclude removed work items by default
`DEFAULT_ITERATION_PATH`	-	Default iteration path for queries
`DEFAULT_AREA_PATH`	-	Default area path for queries
`DEFAULT_ACTIVE_STATES`	`Active,New,In Progress,To Do,Doing`	Default active states
`DEFAULT_COMPLETED_STATES`	`Closed,Done,Resolved`	Default completed states
`DEFAULT_REVIEW_STATES`	`Code Review,Testing,Approved`	Default review states

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:

Go to https://dev.azure.com/{organization}/_usersSettings/tokens
Click "New Token"
Configure the token with appropriate permissions:
- Work Items: Read
- Project and Team: Read
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

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

Testing

# Install development dependencies
uv sync

# Run the server in development mode
python main.py

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

Troubleshooting

Common Issues

Authentication Errors: Verify your PAT has the correct permissions and hasn't expired
Project Not Found: Check that the organization and project names are correct
Network Issues: Ensure you can access Azure DevOps from your network
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

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

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

A Model Context Protocol server that integrates with Azure DevOps, enabling users to query work items, access backlogs, and perform various Azure DevOps operations through a standardized interface.

Related MCP Servers

azure-devops-mcp
RyanCardin15
A
security
A
license
A
quality
This server provides a convenient API for interacting with Azure DevOps services, enabling AI assistants and other tools to manage work items, code repositories, boards, sprints, and more. Built with the Model Context Protocol, it provides a standardized interface for communicating with Azure DevOps
Last updated -
96
43
43
TypeScript
MIT License
Azure DevOps MCP Server
Tiberriver256
A
security
A
license
A
quality
A Model Context Protocol server that enables AI assistants to interact with Azure DevOps resources including projects, work items, repositories, pull requests, branches, and pipelines through a standardized protocol.
Last updated -
15
1,436
277
TypeScript
MIT License
Azure DevOps MCP Server
kevinmeyvaert
-
security
F
license
-
quality
A reference server implementation for the Model Context Protocol that enables AI assistants to interact with Azure DevOps resources and perform operations such as project management, work item tracking, repository operations, and code search programmatically.
Last updated -
7
TypeScript
MCP Azure DevOps Server
Vortiago
A
security
A
license
A
quality
A Model Context Protocol server that enables AI assistants to interact with Azure DevOps services, allowing users to query work items with plans to support creating/updating items, managing pipelines, handling pull requests, and administering sprints and branch policies.
Last updated -
9
71
Python
MIT License

View all related MCP servers