Azure DevOps MCP Server

1# Azure DevOps MCP Server
2 
3A Model Context Protocol (MCP) server implementation for Azure DevOps, allowing AI assistants to interact with Azure DevOps APIs through a standardized protocol.
4 
5## Overview
6 
7This server implements the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) for Azure DevOps, enabling AI assistants like Claude to interact with Azure DevOps resources securely. The server acts as a bridge between AI models and Azure DevOps APIs, providing a standardized way to:
8 
9- Access and manage projects, work items, repositories, and more
10- Create and update work items, branches, and pull requests
11- Execute common DevOps workflows through natural language
12- Access repository content via standardized resource URIs
13- Safely authenticate and interact with Azure DevOps resources
14 
15## Server Structure
16 
17The server is structured around the Model Context Protocol (MCP) for communicating with AI assistants. It provides tools for interacting with Azure DevOps resources including:
18 
19- Projects
20- Work Items
21- Repositories
22- Pull Requests
23- Branches
24- Pipelines
25 
26### Core Components
27 
28- **AzureDevOpsServer**: Main server class that initializes the MCP server and registers tools
29- **Feature Modules**: Organized by feature area (work-items, projects, repositories, etc.)
30- **Request Handlers**: Each feature module provides request identification and handling functions
31- **Tool Handlers**: Modular functions for each Azure DevOps operation
32- **Configuration**: Environment-based configuration for organization URL, PAT, etc.
33 
34The server uses a feature-based architecture where each feature area (like work-items, projects, repositories) is encapsulated in its own module. This makes the codebase more maintainable and easier to extend with new features.
35 
36## Getting Started
37 
38### Prerequisites
39 
40- Node.js (v16+)
41- npm or yarn
42- Azure DevOps account with appropriate access
43- Authentication credentials (see [Authentication Guide](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/authentication.md) for details):
44  - Personal Access Token (PAT), or
45  - Azure Identity credentials, or
46  - Azure CLI login
47 
48### Running from npm (npx)
49 
50If you just want to run the **published** server package, you **do not** need to clone or build this repository:
51 
52```bash
53npx -y @tiberriver256/mcp-server-azure-devops
54```
55 
56### Running locally (from source)
57 
58From a checkout of this repository:
59 
60```bash
61npm ci
62cp .env.example .env   # then edit values
63npm run build
64npm start              # runs: node dist/index.js
65```
66 
67For iterative development (auto-reload):
68 
69```bash
70npm run dev            # runs src/index.ts via ts-node-dev
71```
72 
73### Usage with Claude Desktop/Cursor AI
74 
75To integrate with Claude Desktop or Cursor AI, add one of the following configurations to your configuration file.
76 
77#### Azure Identity Authentication
78 
79Be sure you are logged in to Azure CLI with `az login` then add the following:
80 
81```json
82{
83  "mcpServers": {
84    "azureDevOps": {
85      "command": "npx",
86      "args": ["-y", "@tiberriver256/mcp-server-azure-devops"],
87      "env": {
88        "AZURE_DEVOPS_ORG_URL": "https://dev.azure.com/your-organization",
89        "AZURE_DEVOPS_AUTH_METHOD": "azure-identity",
90        "AZURE_DEVOPS_DEFAULT_PROJECT": "your-project-name"
91      }
92    }
93  }
94}
95```
96 
97#### Personal Access Token (PAT) Authentication
98 
99```json
100{
101  "mcpServers": {
102    "azureDevOps": {
103      "command": "npx",
104      "args": ["-y", "@tiberriver256/mcp-server-azure-devops"],
105      "env": {
106        "AZURE_DEVOPS_ORG_URL": "https://dev.azure.com/your-organization",
107        "AZURE_DEVOPS_AUTH_METHOD": "pat",
108        "AZURE_DEVOPS_PAT": "<YOUR_PAT>",
109        "AZURE_DEVOPS_DEFAULT_PROJECT": "your-project-name"
110      }
111    }
112  }
113}
114```
115 
116Azure DevOps Server (on-prem) requires PAT authentication. Example:
117 
118```json
119{
120  "mcpServers": {
121    "azureDevOps": {
122      "command": "npx",
123      "args": ["-y", "@tiberriver256/mcp-server-azure-devops"],
124      "env": {
125        "AZURE_DEVOPS_ORG_URL": "https://server:8080/tfs/DefaultCollection",
126        "AZURE_DEVOPS_AUTH_METHOD": "pat",
127        "AZURE_DEVOPS_PAT": "<YOUR_PAT>",
128        "AZURE_DEVOPS_DEFAULT_PROJECT": "your-project-name"
129      }
130    }
131  }
132}
133```
134 
135For detailed configuration instructions and more authentication options, see the [Authentication Guide](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/authentication.md).
136 
137## Authentication Methods
138 
139This server supports multiple authentication methods for connecting to Azure DevOps APIs. For detailed setup instructions, configuration examples, and troubleshooting tips, see the [Authentication Guide](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/authentication.md).
140 
141### Supported Authentication Methods
142 
1431. **Personal Access Token (PAT)** - Simple token-based authentication
1442. **Azure Identity (DefaultAzureCredential)** - Flexible authentication using the Azure Identity SDK
1453. **Azure CLI** - Authentication using your Azure CLI login
146 
147Example configuration files for each authentication method are available in the [examples directory](https://github.com/tiberriver256/mcp-server-azure-devops/tree/main/docs/examples).
148 
149Azure DevOps Server (on-prem) supports PAT authentication only. Azure Identity and Azure CLI are supported for Azure DevOps Services.
150 
151## Environment Variables
152 
153For a complete list of environment variables and their descriptions, see the [Authentication Guide](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/authentication.md#configuration-reference).
154 
155Key environment variables include:
156 
157| Variable                       | Description                                                                        | Required                     | Default          |
158| ------------------------------ | ---------------------------------------------------------------------------------- | ---------------------------- | ---------------- |
159| `AZURE_DEVOPS_AUTH_METHOD`     | Authentication method (`pat`, `azure-identity`, or `azure-cli`) - case-insensitive | No                           | `azure-identity` |
160| `AZURE_DEVOPS_ORG_URL`         | Full URL to your Azure DevOps organization or Server collection (e.g., `https://server:8080/tfs/DefaultCollection`) | Yes                          | -                |
161| `AZURE_DEVOPS_PAT`             | Personal Access Token (for PAT auth)                                               | Only with PAT auth           | -                |
162| `AZURE_DEVOPS_DEFAULT_PROJECT` | Default project if none specified                                                  | No                           | -                |
163| `AZURE_DEVOPS_API_VERSION`     | API version to use                                                                 | No                           | Latest           |
164| `AZURE_TENANT_ID`              | Azure AD tenant ID (for service principals)                                        | Only with service principals | -                |
165| `AZURE_CLIENT_ID`              | Azure AD application ID (for service principals)                                   | Only with service principals | -                |
166| `AZURE_CLIENT_SECRET`          | Azure AD client secret (for service principals)                                    | Only with service principals | -                |
167| `LOG_LEVEL`                    | Logging level (debug, info, warn, error)                                           | No                           | info             |
168 
169## Troubleshooting Authentication
170 
171For detailed troubleshooting information for each authentication method, see the [Authentication Guide](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/authentication.md#troubleshooting-authentication-issues).
172 
173Common issues include:
174 
175- Invalid or expired credentials
176- Insufficient permissions
177- Network connectivity problems
178- Configuration errors
179 
180## Authentication Implementation Details
181 
182For technical details about how authentication is implemented in the Azure DevOps MCP server, see the [Authentication Guide](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/authentication.md) and the source code in the `src/auth` directory.
183 
184## Available Tools
185 
186The Azure DevOps MCP server provides a variety of tools for interacting with Azure DevOps resources. For detailed documentation on each tool, please refer to the corresponding documentation.
187 
188### User Tools
189 
190- `get_me`: Get details of the authenticated user (id, displayName, email) (Azure DevOps Services only)
191 
192### Organization Tools
193 
194- `list_organizations`: List all accessible organizations (Azure DevOps Services only)
195 
196### Project Tools
197 
198- `list_projects`: List all projects in an organization
199- `get_project`: Get details of a specific project
200- `get_project_details`: Get comprehensive details of a project including process, work item types, and teams
201 
202### Repository Tools
203 
204- `list_repositories`: List all repositories in a project
205- `get_repository`: Get details of a specific repository
206- `get_repository_details`: Get detailed information about a repository including statistics and refs
207- `get_file_content`: Get content of a file or directory from a repository
208- `get_repository_tree`: List a repository's file tree from any path and depth
209- `create_branch`: Create a new branch from an existing one
210- `create_commit`: Commit multiple file changes to a branch using unified diffs or search/replace instructions
211 
212### Work Item Tools
213 
214- `get_work_item`: Retrieve a work item by ID
215- `create_work_item`: Create a new work item
216- `update_work_item`: Update an existing work item
217- `list_work_items`: List work items in a project
218- `manage_work_item_link`: Add, remove, or update links between work items
219 
220### Search Tools
221 
222- `search_code`: Search for code across repositories in a project
223- `search_wiki`: Search for content across wiki pages in a project
224- `search_work_items`: Search for work items across projects in Azure DevOps
225 
226### Pipelines Tools
227 
228- `list_pipelines`: List pipelines in a project
229- `get_pipeline`: Get details of a specific pipeline
230- `list_pipeline_runs`: List recent runs for a pipeline with optional filters
231- `get_pipeline_run`: Get detailed run information and artifact summaries
232- `download_pipeline_artifact`: Download a single artifact file as text
233- `pipeline_timeline`: Retrieve the stage and job timeline for a run
234- `get_pipeline_log`: Retrieve raw or JSON-formatted log content
235- `trigger_pipeline`: Trigger a pipeline run with customizable parameters
236 
237### Wiki Tools
238 
239- `get_wikis`: List all wikis in a project
240- `get_wiki_page`: Get content of a specific wiki page as plain text
241 
242### Pull Request Tools
243 
244- [`create_pull_request`](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/tools/pull-requests.md#create_pull_request) - Create a new pull request
245- [`get_pull_request`](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/tools/pull-requests.md#get_pull_request) - Get a pull request by ID
246- [`list_pull_requests`](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/tools/pull-requests.md#list_pull_requests) - List pull requests in a repository
247- [`add_pull_request_comment`](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/tools/pull-requests.md#add_pull_request_comment) - Add a comment to a pull request
248- [`get_pull_request_comments`](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/tools/pull-requests.md#get_pull_request_comments) - Get comments from a pull request
249- [`update_pull_request`](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/tools/pull-requests.md#update_pull_request) - Update an existing pull request (title, description, status, draft state, reviewers, work items)
250- [`get_pull_request_changes`](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/tools/pull-requests.md#get_pull_request_changes) - List changes in a pull request and policy evaluation status
251- [`get_pull_request_checks`](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/docs/tools/pull-requests.md#get_pull_request_checks) - Summarize status checks, policy evaluations, and their related pipelines
252 
253For comprehensive documentation on all tools, see the [Tools Documentation](https://github.com/tiberriver256/mcp-server-azure-devops/tree/main/docs/tools).
254 
255## Contributing
256 
257Contributions are welcome! Please see [CONTRIBUTING.md](https://github.com/tiberriver256/mcp-server-azure-devops/blob/main/CONTRIBUTING.md) for contribution guidelines.
258 
259## Star History
260 
261[![Star History Chart](https://api.star-history.com/svg?repos=tiberriver256/mcp-server-azure-devops&type=Date)](https://www.star-history.com/#tiberriver256/mcp-server-azure-devops&Date)
262 
263## License
264 
265MIT
266