Azure DevOps MCP Server

# 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**: ```bash git clone https://github.com/jhlia0/azure-devops-mcp.git cd mcp-server-azure-devops ``` 2. **Install dependencies**: ```bash uv sync ``` 3. **Configure environment variables**: ```bash 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: ```bash 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**: ```bash 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 ```python # 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 ```python # 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 ```python # 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 ```python # 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 ```python # 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 ```bash # 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: ```bash 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](https://github.com/jlowin/fastmcp) - The MCP framework used by this server - [Azure DevOps REST API](https://docs.microsoft.com/en-us/rest/api/azure/devops/) - Official API documentation