# ADO MCP
An MCP (Model Context Protocol) server that provides Azure DevOps integration for AI assistants and development tools. Enables your AI assistant to list projects, run pipelines, analyze failures, view logs, and troubleshoot builds directly from your chat interface.
📚 **[Full Documentation](https://ado-mcp.readthedocs.io/)** | 🚀 **[Quick Start](#prerequisites)** | 🛠️ **[API Reference](https://ado-mcp.readthedocs.io/en/latest/api.html)**
## Prerequisites
You'll need these installed before setting up the MCP server:
1. **UV** (Python package runner):
```bash
# Install UV (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh
```
2. **Azure CLI with DevOps extension**:
```bash
# Install Azure CLI
# macOS: brew install azure-cli
# Windows: winget install Microsoft.AzureCLI
# Linux: curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash
# Install Azure DevOps extension
az extension add --name azure-devops
```
3. **Authenticate with Azure DevOps**:
```bash
# Login to Azure DevOps with your PAT
az devops login --organization https://dev.azure.com/YourOrg
```
When prompted, enter your Personal Access Token. This stores your credentials securely in the system keyring.
4. **Test the setup**:
```bash
# Test that everything works
uvx ado-mcp --help
```
## Installation
<details>
<summary><b>Install in Claude Desktop</b></summary>
1. **macOS Configuration** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"ado-mcp": {
"command": "uvx",
"args": ["ado-mcp"],
"env": {
"ADO_ORGANIZATION_URL": "https://dev.azure.com/YourOrg"
}
}
}
}
```
2. **Windows Configuration** (`%APPDATA%\Claude\claude_desktop_config.json`):
```json
{
"mcpServers": {
"ado-mcp": {
"command": "uvx",
"args": ["ado-mcp"],
"env": {
"ADO_ORGANIZATION_URL": "https://dev.azure.com/YourOrg"
}
}
}
}
```
3. **Restart Claude Desktop** to load the MCP server.
**Note**: `uvx` automatically downloads and runs the latest version. No manual installation needed!
</details>
<details>
<summary><b>Install in Claude Code</b></summary>
1. **Add the MCP server**:
```bash
# Add to local scope (project-specific)
claude mcp add ado-mcp uvx ado-mcp -e ADO_ORGANIZATION_URL=https://dev.azure.com/YourOrg
# Or add to user scope (available across all projects)
claude mcp add ado-mcp uvx ado-mcp -e ADO_ORGANIZATION_URL=https://dev.azure.com/YourOrg -s user
```
2. **Verify the installation**:
```bash
# List configured MCP servers
claude mcp list
```
3. **Use in Claude Code**:
- Reference Azure DevOps resources with `@ado-mcp:...`
- Use slash commands like `/mcp__ado-mcp__list_projects`
- Ask Claude to interact with your Azure DevOps pipelines directly
**Note**: Claude Code automatically handles the `uvx` execution and authentication via Azure CLI.
</details>
<details>
<summary><b>Install in Cursor</b></summary>
1. Go to: `Settings` → `Cursor Settings` → `MCP` → `Add new global MCP server`
2. **Configuration**:
```json
{
"name": "ado-mcp",
"command": "uvx",
"args": ["ado-mcp-raboley"],
"env": {
"ADO_ORGANIZATION_URL": "https://dev.azure.com/YourOrg"
}
}
```
3. **Save** and restart Cursor.
</details>
<details>
<summary><b>Install in VS Code with Continue</b></summary>
1. **Install Continue extension** from VS Code marketplace.
2. **Configure in `~/.continue/config.json`**:
```json
{
"models": [...],
"mcpServers": [
{
"name": "ado-mcp",
"command": "uvx",
"args": ["ado-mcp"],
"env": {
"ADO_ORGANIZATION_URL": "https://dev.azure.com/YourOrg"
}
}
]
}
```
3. **Restart VS Code** to load the configuration.
</details>
<details>
<summary><b>Install in Zed</b></summary>
1. **Open Zed settings** (`Cmd+,` on macOS, `Ctrl+,` on Linux/Windows).
2. **Add to MCP settings**:
```json
{
"language_models": {
"mcp_servers": {
"ado-mcp": {
"command": "uvx",
"args": ["ado-mcp"],
"env": {
"ADO_ORGANIZATION_URL": "https://dev.azure.com/YourOrg"
}
}
}
}
}
```
3. **Restart Zed** to apply changes.
</details>
<details>
<summary><b>Install in any MCP-compatible client</b></summary>
The server can be used with any MCP-compatible client:
**Command**: `uvx ado-mcp`
**Required environment variable**:
- `ADO_ORGANIZATION_URL`: Your Azure DevOps organization URL (e.g., `https://dev.azure.com/YourOrg`)
**Connection details**:
- **Protocol**: stdio
- **Capabilities**: Tools, Resources
- **Transport**: Standard input/output
**Authentication**: Automatically uses Azure CLI credentials from `az devops login`
</details>
<details>
<summary><b>Alternative: Environment Variable Authentication</b></summary>
If you prefer not to use Azure CLI, you can set environment variables directly:
1. **Set environment variables**:
```bash
export AZURE_DEVOPS_EXT_PAT="your-personal-access-token"
export ADO_ORGANIZATION_URL="https://dev.azure.com/YourOrg"
```
2. **Configure with environment variables**:
```json
{
"mcpServers": {
"ado-mcp": {
"command": "uvx",
"args": ["ado-mcp"]
}
}
}
```
**⚠️ Security Note**: This method requires storing tokens as environment variables. The Azure CLI method is more secure as it stores credentials in the system keyring.
</details>
## Features
### 🔧 Pipeline Operations
- **List and manage pipelines** - View all pipelines in your Azure DevOps projects
- **Run pipelines** - Trigger pipeline execution with real-time status monitoring
- **Pipeline analysis** - Get detailed failure summaries, logs, and timeline analysis
- **Build management** - Track build results and access build artifacts
### 🔍 Smart Search & Discovery
- **Name-based lookups** - Find projects and pipelines using fuzzy matching
- **URL parsing** - Extract pipeline information from Azure DevOps web URLs
- **Project exploration** - Browse available projects and their pipelines
### 📊 Logs & Debugging
- **Failure analysis** - Intelligent root cause analysis for failed pipelines
- **Step-by-step logs** - Access detailed logs for individual pipeline steps
- **Timeline visualization** - See execution flow and timing information
- **Log filtering** - Search and filter logs by step name or content
### 🔐 Flexible Authentication
- **Personal Access Tokens** - Traditional PAT-based authentication
- **Azure CLI integration** - Seamless integration with existing Azure CLI sessions
- **Multiple auth fallbacks** - Automatic fallback between authentication methods
### ⚡ Performance & Caching
- **Intelligent caching** - Fast project and pipeline lookups with automatic cache invalidation
- **Batch operations** - Efficient handling of multiple requests
- **Resource optimization** - MCP resources for commonly accessed data
## Development Setup
1. **Install Dependencies**:
```bash
task install
```
2. **Set up Authentication**:
The MCP server supports multiple authentication methods (in order of precedence):
### Option 1: Personal Access Token (PAT)
**Environment Variable Method:**
```bash
task setup-env
```
This creates a `.env` file with your Personal Access Token (PAT) and other necessary variables.
**Direct Configuration:**
```bash
export AZURE_DEVOPS_EXT_PAT="your-personal-access-token"
export ADO_ORGANIZATION_URL="https://dev.azure.com/YourOrg"
```
### Option 2: Azure CLI Authentication (Recommended)
If you already use Azure CLI, you can authenticate using your existing session:
```bash
# Login to Azure (if not already logged in)
az login
# The MCP server will automatically use your Azure CLI credentials
task run
```
**Benefits of Azure CLI authentication:**
- No need to manage Personal Access Tokens
- Uses your existing Azure credentials
- More secure than storing PATs
- Automatically refreshes tokens
**Note:** Azure CLI authentication requires the user to be logged in with an account that has access to the Azure DevOps organization.
## Testing
The ado-mcp project uses a Terraform-based test infrastructure that creates isolated test environments.
### Quick Test Setup
1. **Configure environment**:
```bash
cp .env.example .env # Edit with your Azure DevOps details
```
2. **Provision test environment**:
```bash
task ado-up # Creates Azure DevOps project and infrastructure
```
3. **Run tests**:
```bash
task test
```
4. **Clean up**:
```bash
task ado-down # Destroys the test environment
```
### Test Commands
- **Run all tests** (parallel):
```bash
task test
```
- **Run single test**:
```bash
task test-single TEST_NAME=tests/test_example.py::test_function_name
```
- **Test coverage**:
```bash
task coverage
```
📚 **[Detailed Testing Setup Guide](docs/TESTING_SETUP.md)**
- **Setup Azure DevOps CLI** (for Azure DevOps CLI commands):
```bash
task setup-ado-cli
```
This will:
- Install Azure CLI if needed
- Install Azure DevOps CLI extension if needed
- Login to Azure DevOps CLI using your PAT (from AZURE_DEVOPS_EXT_PAT)
- Configure default organization and project
**Note**: This is for `az devops` commands and does NOT enable the Azure CLI authentication test, which requires full Azure authentication (`az login`).
## Usage
- **Run the MCP Server**:
```bash
task run
```
- **Inspect the MCP Server**:
```bash
task inspect
```
## Getting Started
Once installed and configured, you can use the MCP server through your AI assistant. Here are some common tasks:
### Basic Operations
**List all projects:**
```
Show me all Azure DevOps projects in my organization.
```
**Find and run a pipeline:**
```
Find the "deploy-production" pipeline in the "MyApp" project and run it.
```
**Check recent build failures:**
```
What pipelines have failed recently? Show me the failure details.
```
### Pipeline Analysis
**Analyze a failed build from a URL:**
```
Analyze this failed build: https://dev.azure.com/MyOrg/MyProject/_build/results?buildId=123
```
**Get detailed failure logs:**
```
Show me the detailed logs for the failed steps in pipeline run 456.
```
**Compare pipeline runs:**
```
Compare the latest run of "ci-pipeline" with the previous successful run.
```
### Advanced Usage
**Monitor pipeline execution:**
```
Run the "integration-tests" pipeline and monitor its progress. Alert me when it completes.
```
**Create deployment insights:**
```
Generate a summary of all deployment pipeline runs from the last week.
```
**Troubleshoot build issues:**
```
Help me troubleshoot why the "build-and-test" pipeline keeps failing on the test step.
```
## Troubleshooting
### Authentication Issues
**"No authentication method available" error:**
```bash
# Check if you're logged into Azure DevOps
az devops configure --list
# If not configured, login with your PAT
az devops login --organization https://dev.azure.com/YourOrg
```
**"Authentication failed" with sign-in page response:**
```bash
# Your PAT might be expired, login again
az devops logout
az devops login --organization https://dev.azure.com/YourOrg
```
**Permission errors:**
- Ensure your PAT has the following scopes:
- **Build**: Read & execute
- **Project and team**: Read
- **Release**: Read, write, & execute
- **Code**: Read (if accessing repositories)
### Installation Issues
**"uvx ado-mcp" not working:**
```bash
# Check UV installation
uvx --version
# Install UV if needed
curl -LsSf https://astral.sh/uv/install.sh | sh
# Test the package
uvx ado-mcp --help
```
**Azure CLI not found:**
```bash
# Install Azure CLI (Ubuntu/Debian)
curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash
# Install Azure CLI (macOS)
brew install azure-cli
# Install Azure CLI (Windows)
# Download and install from: https://aka.ms/installazurecliwindows
```
---
## Development Setup
If you want to contribute to this project or run it from source:
1. **Install Dependencies**:
```bash
task install
```
2. **Set up Authentication**:
The MCP server supports multiple authentication methods (in order of precedence):
### Option 1: Personal Access Token (PAT)
**Environment Variable Method:**
```bash
task setup-env
```
This creates a `.env` file with your Personal Access Token (PAT) and other necessary variables.
**Direct Configuration:**
```bash
export AZURE_DEVOPS_EXT_PAT="your-personal-access-token"
export ADO_ORGANIZATION_URL="https://dev.azure.com/YourOrg"
```
### Option 2: Azure CLI Authentication (Recommended)
If you already use Azure CLI, you can authenticate using your existing session:
```bash
# Login to Azure (if not already logged in)
az login
# The MCP server will automatically use your Azure CLI credentials
task run
```
**Benefits of Azure CLI authentication:**
- No need to manage Personal Access Tokens
- Uses your existing Azure credentials
- More secure than storing PATs
- Automatically refreshes tokens
**Note:** Azure CLI authentication requires the user to be logged in with an account that has access to the Azure DevOps organization.
## Testing
The ado-mcp project uses a Terraform-based test infrastructure that creates isolated test environments.
### Quick Test Setup
1. **Configure environment**:
```bash
cp .env.example .env # Edit with your Azure DevOps details
```
2. **Provision test environment**:
```bash
task ado-up # Creates Azure DevOps project and infrastructure
```
3. **Run tests**:
```bash
task test
```
4. **Clean up**:
```bash
task ado-down # Destroys the test environment
```
### Test Commands
- **Run all tests** (parallel):
```bash
task test
```
- **Run single test**:
```bash
task test-single TEST_NAME=tests/test_example.py::test_function_name
```
- **Test coverage**:
```bash
task coverage
```
📚 **[Detailed Testing Setup Guide](docs/TESTING_SETUP.md)**
- **Setup Azure DevOps CLI** (for Azure DevOps CLI commands):
```bash
task setup-ado-cli
```
This will:
- Install Azure CLI if needed
- Install Azure DevOps CLI extension if needed
- Login to Azure DevOps CLI using your PAT (from AZURE_DEVOPS_EXT_PAT)
- Configure default organization and project
**Note**: This is for `az devops` commands and does NOT enable the Azure CLI authentication test, which requires full Azure authentication (`az login`).
## Usage
- **Run the MCP Server**:
```bash
task run
```
- **Inspect the MCP Server**:
```bash
task inspect
```
## Documentation
- **View documentation locally**:
```bash
task docs-serve
```
This automatically builds the docs and serves them at http://localhost:8000
The documentation is built with [Sphinx](https://www.sphinx-doc.org/) and hosted on [Read the Docs](https://ado-mcp.readthedocs.io/).
## Working with Azure DevOps URLs
### Understanding Azure DevOps URL Structure
When working with Azure DevOps URLs from the web interface, it's important to understand the difference between **build/run IDs** and **pipeline definition IDs**:
**Example URL**: `https://dev.azure.com/RussellBoley/ado-mcp/_build/results?buildId=324&view=results`
- **Organization**: `RussellBoley` (from the URL path)
- **Project**: `ado-mcp` (from the URL path)
- **buildId=324**: This is a **run ID** (specific execution instance), NOT a pipeline definition ID
### Getting Pipeline Information from Build URLs
To work with a specific build/run from an Azure DevOps URL:
1. **Extract URL components**:
- Organization: `RussellBoley`
- Project: `ado-mcp`
- Build/Run ID: `324` (from `buildId` parameter)
2. **Use `get_build_by_id` to find the pipeline**:
```python
# Get build details to find the pipeline definition
build_details = await client.call_tool("get_build_by_id", {
"project_id": "49e895da-15c6-4211-97df-65c547a59c22", # ado-mcp project ID
"build_id": 324 # The buildId from the URL
})
# Extract pipeline information
pipeline_id = build_details.data["definition"]["id"] # e.g., 84
pipeline_name = build_details.data["definition"]["name"] # e.g., "log-test-complex"
```
3. **Then use pipeline-specific tools**:
```python
# Get detailed run information
run_details = await client.call_tool("get_pipeline_run", {
"project_id": "49e895da-15c6-4211-97df-65c547a59c22",
"pipeline_id": pipeline_id, # 84
"run_id": 324 # Same as buildId
})
# Get failure analysis if needed
failure_summary = await client.call_tool("get_pipeline_failure_summary", {
"project_id": "49e895da-15c6-4211-97df-65c547a59c22",
"pipeline_id": pipeline_id,
"run_id": 324
})
```
### Common Mistake to Avoid
❌ **Don't do this**:
```python
# This will fail - you can't guess the pipeline_id
await client.call_tool("get_pipeline_run", {
"project_id": "49e895da-15c6-4211-97df-65c547a59c22",
"pipeline_id": 15, # Wrong! This is just a guess
"run_id": 324
})
```
✅ **Do this instead**:
```python
# First, get the build details to find the correct pipeline_id
build_data = await client.call_tool("get_build_by_id", {
"project_id": "49e895da-15c6-4211-97df-65c547a59c22",
"build_id": 324 # buildId from URL
})
pipeline_id = build_data.data["definition"]["id"] # Now you have the correct pipeline_id
# Then use it for pipeline-specific operations
await client.call_tool("get_pipeline_run", {
"project_id": "49e895da-15c6-4211-97df-65c547a59c22",
"pipeline_id": pipeline_id, # Correct pipeline_id
"run_id": 324
})
```
### Available Tools for Build/Pipeline Analysis
- **`get_build_by_id`**: Get build details and extract pipeline information from a build/run ID
- **`get_pipeline_run`**: Get detailed run information (requires both pipeline_id and run_id)
- **`get_pipeline_failure_summary`**: Analyze failures with root cause analysis
- **`get_failed_step_logs`**: Get logs for failed steps
- **`get_pipeline_timeline`**: Get execution timeline
- **`list_pipeline_logs`**: List all available logs
- **`get_log_content_by_id`**: Get specific log content
- **`run_pipeline_and_get_outcome`**: Run a pipeline and wait for completion with analysis
Raw data
{
"_id": null,
"home_page": null,
"name": "ado-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "azure-devops, mcp, model-context-protocol, ci-cd, pipelines, automation, devops, azure, llm, ai-tools",
"author": null,
"author_email": "Russell Boley <countrypeaches@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/51/8a/417dea08486bb10151128fdd62ab4e328ecf27437900c68eacb46e0ad635/ado_mcp-0.0.1.tar.gz",
"platform": null,
"description": "# ADO MCP\n\nAn MCP (Model Context Protocol) server that provides Azure DevOps integration for AI assistants and development tools. Enables your AI assistant to list projects, run pipelines, analyze failures, view logs, and troubleshoot builds directly from your chat interface.\n\n\ud83d\udcda **[Full Documentation](https://ado-mcp.readthedocs.io/)** | \ud83d\ude80 **[Quick Start](#prerequisites)** | \ud83d\udee0\ufe0f **[API Reference](https://ado-mcp.readthedocs.io/en/latest/api.html)**\n\n## Prerequisites\n\nYou'll need these installed before setting up the MCP server:\n\n1. **UV** (Python package runner):\n ```bash\n # Install UV (if not already installed)\n curl -LsSf https://astral.sh/uv/install.sh | sh\n ```\n\n2. **Azure CLI with DevOps extension**:\n ```bash\n # Install Azure CLI\n # macOS: brew install azure-cli\n # Windows: winget install Microsoft.AzureCLI\n # Linux: curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash\n \n # Install Azure DevOps extension\n az extension add --name azure-devops\n ```\n\n3. **Authenticate with Azure DevOps**:\n ```bash\n # Login to Azure DevOps with your PAT\n az devops login --organization https://dev.azure.com/YourOrg\n ```\n \n When prompted, enter your Personal Access Token. This stores your credentials securely in the system keyring.\n\n4. **Test the setup**:\n ```bash\n # Test that everything works\n uvx ado-mcp --help\n ```\n\n## Installation\n\n<details>\n<summary><b>Install in Claude Desktop</b></summary>\n\n1. **macOS Configuration** (`~/Library/Application Support/Claude/claude_desktop_config.json`):\n ```json\n {\n \"mcpServers\": {\n \"ado-mcp\": {\n \"command\": \"uvx\",\n \"args\": [\"ado-mcp\"],\n \"env\": {\n \"ADO_ORGANIZATION_URL\": \"https://dev.azure.com/YourOrg\"\n }\n }\n }\n }\n ```\n\n2. **Windows Configuration** (`%APPDATA%\\Claude\\claude_desktop_config.json`):\n ```json\n {\n \"mcpServers\": {\n \"ado-mcp\": {\n \"command\": \"uvx\",\n \"args\": [\"ado-mcp\"],\n \"env\": {\n \"ADO_ORGANIZATION_URL\": \"https://dev.azure.com/YourOrg\"\n }\n }\n }\n }\n ```\n\n3. **Restart Claude Desktop** to load the MCP server.\n\n**Note**: `uvx` automatically downloads and runs the latest version. No manual installation needed!\n\n</details>\n\n<details>\n<summary><b>Install in Claude Code</b></summary>\n\n1. **Add the MCP server**:\n ```bash\n # Add to local scope (project-specific)\n claude mcp add ado-mcp uvx ado-mcp -e ADO_ORGANIZATION_URL=https://dev.azure.com/YourOrg\n \n # Or add to user scope (available across all projects)\n claude mcp add ado-mcp uvx ado-mcp -e ADO_ORGANIZATION_URL=https://dev.azure.com/YourOrg -s user\n ```\n\n2. **Verify the installation**:\n ```bash\n # List configured MCP servers\n claude mcp list\n ```\n\n3. **Use in Claude Code**:\n - Reference Azure DevOps resources with `@ado-mcp:...`\n - Use slash commands like `/mcp__ado-mcp__list_projects`\n - Ask Claude to interact with your Azure DevOps pipelines directly\n\n**Note**: Claude Code automatically handles the `uvx` execution and authentication via Azure CLI.\n\n</details>\n\n<details>\n<summary><b>Install in Cursor</b></summary>\n\n1. Go to: `Settings` \u2192 `Cursor Settings` \u2192 `MCP` \u2192 `Add new global MCP server`\n\n2. **Configuration**:\n ```json\n {\n \"name\": \"ado-mcp\",\n \"command\": \"uvx\",\n \"args\": [\"ado-mcp-raboley\"],\n \"env\": {\n \"ADO_ORGANIZATION_URL\": \"https://dev.azure.com/YourOrg\"\n }\n }\n ```\n\n3. **Save** and restart Cursor.\n\n</details>\n\n<details>\n<summary><b>Install in VS Code with Continue</b></summary>\n\n1. **Install Continue extension** from VS Code marketplace.\n\n2. **Configure in `~/.continue/config.json`**:\n ```json\n {\n \"models\": [...],\n \"mcpServers\": [\n {\n \"name\": \"ado-mcp\",\n \"command\": \"uvx\",\n \"args\": [\"ado-mcp\"],\n \"env\": {\n \"ADO_ORGANIZATION_URL\": \"https://dev.azure.com/YourOrg\"\n }\n }\n ]\n }\n ```\n\n3. **Restart VS Code** to load the configuration.\n\n</details>\n\n<details>\n<summary><b>Install in Zed</b></summary>\n\n1. **Open Zed settings** (`Cmd+,` on macOS, `Ctrl+,` on Linux/Windows).\n\n2. **Add to MCP settings**:\n ```json\n {\n \"language_models\": {\n \"mcp_servers\": {\n \"ado-mcp\": {\n \"command\": \"uvx\",\n \"args\": [\"ado-mcp\"],\n \"env\": {\n \"ADO_ORGANIZATION_URL\": \"https://dev.azure.com/YourOrg\"\n }\n }\n }\n }\n }\n ```\n\n3. **Restart Zed** to apply changes.\n\n</details>\n\n<details>\n<summary><b>Install in any MCP-compatible client</b></summary>\n\nThe server can be used with any MCP-compatible client:\n\n**Command**: `uvx ado-mcp`\n\n**Required environment variable**:\n- `ADO_ORGANIZATION_URL`: Your Azure DevOps organization URL (e.g., `https://dev.azure.com/YourOrg`)\n\n**Connection details**:\n- **Protocol**: stdio\n- **Capabilities**: Tools, Resources\n- **Transport**: Standard input/output\n\n**Authentication**: Automatically uses Azure CLI credentials from `az devops login`\n\n</details>\n\n<details>\n<summary><b>Alternative: Environment Variable Authentication</b></summary>\n\nIf you prefer not to use Azure CLI, you can set environment variables directly:\n\n1. **Set environment variables**:\n ```bash\n export AZURE_DEVOPS_EXT_PAT=\"your-personal-access-token\"\n export ADO_ORGANIZATION_URL=\"https://dev.azure.com/YourOrg\"\n ```\n\n2. **Configure with environment variables**:\n ```json\n {\n \"mcpServers\": {\n \"ado-mcp\": {\n \"command\": \"uvx\",\n \"args\": [\"ado-mcp\"]\n }\n }\n }\n ```\n\n**\u26a0\ufe0f Security Note**: This method requires storing tokens as environment variables. The Azure CLI method is more secure as it stores credentials in the system keyring.\n\n</details>\n\n## Features\n\n### \ud83d\udd27 Pipeline Operations\n- **List and manage pipelines** - View all pipelines in your Azure DevOps projects\n- **Run pipelines** - Trigger pipeline execution with real-time status monitoring\n- **Pipeline analysis** - Get detailed failure summaries, logs, and timeline analysis\n- **Build management** - Track build results and access build artifacts\n\n### \ud83d\udd0d Smart Search & Discovery\n- **Name-based lookups** - Find projects and pipelines using fuzzy matching\n- **URL parsing** - Extract pipeline information from Azure DevOps web URLs\n- **Project exploration** - Browse available projects and their pipelines\n\n### \ud83d\udcca Logs & Debugging\n- **Failure analysis** - Intelligent root cause analysis for failed pipelines\n- **Step-by-step logs** - Access detailed logs for individual pipeline steps\n- **Timeline visualization** - See execution flow and timing information\n- **Log filtering** - Search and filter logs by step name or content\n\n### \ud83d\udd10 Flexible Authentication\n- **Personal Access Tokens** - Traditional PAT-based authentication\n- **Azure CLI integration** - Seamless integration with existing Azure CLI sessions\n- **Multiple auth fallbacks** - Automatic fallback between authentication methods\n\n### \u26a1 Performance & Caching\n- **Intelligent caching** - Fast project and pipeline lookups with automatic cache invalidation\n- **Batch operations** - Efficient handling of multiple requests\n- **Resource optimization** - MCP resources for commonly accessed data\n\n## Development Setup\n\n1. **Install Dependencies**:\n ```bash\n task install\n ```\n\n2. **Set up Authentication**:\n The MCP server supports multiple authentication methods (in order of precedence):\n\n ### Option 1: Personal Access Token (PAT)\n \n **Environment Variable Method:**\n ```bash\n task setup-env\n ```\n This creates a `.env` file with your Personal Access Token (PAT) and other necessary variables.\n\n **Direct Configuration:**\n ```bash\n export AZURE_DEVOPS_EXT_PAT=\"your-personal-access-token\"\n export ADO_ORGANIZATION_URL=\"https://dev.azure.com/YourOrg\"\n ```\n\n ### Option 2: Azure CLI Authentication (Recommended)\n \n If you already use Azure CLI, you can authenticate using your existing session:\n \n ```bash\n # Login to Azure (if not already logged in)\n az login\n \n # The MCP server will automatically use your Azure CLI credentials\n task run\n ```\n \n **Benefits of Azure CLI authentication:**\n - No need to manage Personal Access Tokens\n - Uses your existing Azure credentials \n - More secure than storing PATs\n - Automatically refreshes tokens\n \n **Note:** Azure CLI authentication requires the user to be logged in with an account that has access to the Azure DevOps organization.\n\n## Testing\n\nThe ado-mcp project uses a Terraform-based test infrastructure that creates isolated test environments.\n\n### Quick Test Setup\n\n1. **Configure environment**:\n ```bash\n cp .env.example .env # Edit with your Azure DevOps details\n ```\n\n2. **Provision test environment**:\n ```bash\n task ado-up # Creates Azure DevOps project and infrastructure\n ```\n\n3. **Run tests**:\n ```bash\n task test\n ```\n\n4. **Clean up**:\n ```bash\n task ado-down # Destroys the test environment\n ```\n\n### Test Commands\n\n- **Run all tests** (parallel):\n ```bash\n task test\n ```\n\n- **Run single test**:\n ```bash\n task test-single TEST_NAME=tests/test_example.py::test_function_name\n ```\n\n- **Test coverage**:\n ```bash\n task coverage\n ```\n\n\ud83d\udcda **[Detailed Testing Setup Guide](docs/TESTING_SETUP.md)**\n\n- **Setup Azure DevOps CLI** (for Azure DevOps CLI commands):\n ```bash\n task setup-ado-cli\n ```\n This will:\n - Install Azure CLI if needed\n - Install Azure DevOps CLI extension if needed\n - Login to Azure DevOps CLI using your PAT (from AZURE_DEVOPS_EXT_PAT)\n - Configure default organization and project\n \n **Note**: This is for `az devops` commands and does NOT enable the Azure CLI authentication test, which requires full Azure authentication (`az login`).\n\n## Usage\n\n- **Run the MCP Server**:\n ```bash\n task run\n ```\n\n- **Inspect the MCP Server**:\n ```bash\n task inspect\n ```\n\n## Getting Started\n\nOnce installed and configured, you can use the MCP server through your AI assistant. Here are some common tasks:\n\n### Basic Operations\n\n**List all projects:**\n```\nShow me all Azure DevOps projects in my organization.\n```\n\n**Find and run a pipeline:**\n```\nFind the \"deploy-production\" pipeline in the \"MyApp\" project and run it.\n```\n\n**Check recent build failures:**\n```\nWhat pipelines have failed recently? Show me the failure details.\n```\n\n### Pipeline Analysis\n\n**Analyze a failed build from a URL:**\n```\nAnalyze this failed build: https://dev.azure.com/MyOrg/MyProject/_build/results?buildId=123\n```\n\n**Get detailed failure logs:**\n```\nShow me the detailed logs for the failed steps in pipeline run 456.\n```\n\n**Compare pipeline runs:**\n```\nCompare the latest run of \"ci-pipeline\" with the previous successful run.\n```\n\n### Advanced Usage\n\n**Monitor pipeline execution:**\n```\nRun the \"integration-tests\" pipeline and monitor its progress. Alert me when it completes.\n```\n\n**Create deployment insights:**\n```\nGenerate a summary of all deployment pipeline runs from the last week.\n```\n\n**Troubleshoot build issues:**\n```\nHelp me troubleshoot why the \"build-and-test\" pipeline keeps failing on the test step.\n```\n\n## Troubleshooting\n\n### Authentication Issues\n\n**\"No authentication method available\" error:**\n```bash\n# Check if you're logged into Azure DevOps\naz devops configure --list\n\n# If not configured, login with your PAT\naz devops login --organization https://dev.azure.com/YourOrg\n```\n\n**\"Authentication failed\" with sign-in page response:**\n```bash\n# Your PAT might be expired, login again\naz devops logout\naz devops login --organization https://dev.azure.com/YourOrg\n```\n\n**Permission errors:**\n- Ensure your PAT has the following scopes:\n - **Build**: Read & execute\n - **Project and team**: Read\n - **Release**: Read, write, & execute\n - **Code**: Read (if accessing repositories)\n\n### Installation Issues\n\n**\"uvx ado-mcp\" not working:**\n```bash\n# Check UV installation\nuvx --version\n\n# Install UV if needed\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Test the package\nuvx ado-mcp --help\n```\n\n**Azure CLI not found:**\n```bash\n# Install Azure CLI (Ubuntu/Debian)\ncurl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash\n\n# Install Azure CLI (macOS)\nbrew install azure-cli\n\n# Install Azure CLI (Windows)\n# Download and install from: https://aka.ms/installazurecliwindows\n```\n\n---\n\n## Development Setup\n\nIf you want to contribute to this project or run it from source:\n\n1. **Install Dependencies**:\n ```bash\n task install\n ```\n\n2. **Set up Authentication**:\n The MCP server supports multiple authentication methods (in order of precedence):\n\n ### Option 1: Personal Access Token (PAT)\n \n **Environment Variable Method:**\n ```bash\n task setup-env\n ```\n This creates a `.env` file with your Personal Access Token (PAT) and other necessary variables.\n\n **Direct Configuration:**\n ```bash\n export AZURE_DEVOPS_EXT_PAT=\"your-personal-access-token\"\n export ADO_ORGANIZATION_URL=\"https://dev.azure.com/YourOrg\"\n ```\n\n ### Option 2: Azure CLI Authentication (Recommended)\n \n If you already use Azure CLI, you can authenticate using your existing session:\n \n ```bash\n # Login to Azure (if not already logged in)\n az login\n \n # The MCP server will automatically use your Azure CLI credentials\n task run\n ```\n \n **Benefits of Azure CLI authentication:**\n - No need to manage Personal Access Tokens\n - Uses your existing Azure credentials \n - More secure than storing PATs\n - Automatically refreshes tokens\n \n **Note:** Azure CLI authentication requires the user to be logged in with an account that has access to the Azure DevOps organization.\n\n## Testing\n\nThe ado-mcp project uses a Terraform-based test infrastructure that creates isolated test environments.\n\n### Quick Test Setup\n\n1. **Configure environment**:\n ```bash\n cp .env.example .env # Edit with your Azure DevOps details\n ```\n\n2. **Provision test environment**:\n ```bash\n task ado-up # Creates Azure DevOps project and infrastructure\n ```\n\n3. **Run tests**:\n ```bash\n task test\n ```\n\n4. **Clean up**:\n ```bash\n task ado-down # Destroys the test environment\n ```\n\n### Test Commands\n\n- **Run all tests** (parallel):\n ```bash\n task test\n ```\n\n- **Run single test**:\n ```bash\n task test-single TEST_NAME=tests/test_example.py::test_function_name\n ```\n\n- **Test coverage**:\n ```bash\n task coverage\n ```\n\n\ud83d\udcda **[Detailed Testing Setup Guide](docs/TESTING_SETUP.md)**\n\n- **Setup Azure DevOps CLI** (for Azure DevOps CLI commands):\n ```bash\n task setup-ado-cli\n ```\n This will:\n - Install Azure CLI if needed\n - Install Azure DevOps CLI extension if needed\n - Login to Azure DevOps CLI using your PAT (from AZURE_DEVOPS_EXT_PAT)\n - Configure default organization and project\n \n **Note**: This is for `az devops` commands and does NOT enable the Azure CLI authentication test, which requires full Azure authentication (`az login`).\n\n## Usage\n\n- **Run the MCP Server**:\n ```bash\n task run\n ```\n\n- **Inspect the MCP Server**:\n ```bash\n task inspect\n ```\n\n## Documentation\n\n- **View documentation locally**:\n ```bash\n task docs-serve\n ```\n \n This automatically builds the docs and serves them at http://localhost:8000\n\nThe documentation is built with [Sphinx](https://www.sphinx-doc.org/) and hosted on [Read the Docs](https://ado-mcp.readthedocs.io/).\n\n## Working with Azure DevOps URLs\n\n### Understanding Azure DevOps URL Structure\n\nWhen working with Azure DevOps URLs from the web interface, it's important to understand the difference between **build/run IDs** and **pipeline definition IDs**:\n\n**Example URL**: `https://dev.azure.com/RussellBoley/ado-mcp/_build/results?buildId=324&view=results`\n\n- **Organization**: `RussellBoley` (from the URL path)\n- **Project**: `ado-mcp` (from the URL path)\n- **buildId=324**: This is a **run ID** (specific execution instance), NOT a pipeline definition ID\n\n### Getting Pipeline Information from Build URLs\n\nTo work with a specific build/run from an Azure DevOps URL:\n\n1. **Extract URL components**:\n - Organization: `RussellBoley`\n - Project: `ado-mcp` \n - Build/Run ID: `324` (from `buildId` parameter)\n\n2. **Use `get_build_by_id` to find the pipeline**:\n ```python\n # Get build details to find the pipeline definition\n build_details = await client.call_tool(\"get_build_by_id\", {\n \"project_id\": \"49e895da-15c6-4211-97df-65c547a59c22\", # ado-mcp project ID\n \"build_id\": 324 # The buildId from the URL\n })\n \n # Extract pipeline information\n pipeline_id = build_details.data[\"definition\"][\"id\"] # e.g., 84\n pipeline_name = build_details.data[\"definition\"][\"name\"] # e.g., \"log-test-complex\"\n ```\n\n3. **Then use pipeline-specific tools**:\n ```python\n # Get detailed run information\n run_details = await client.call_tool(\"get_pipeline_run\", {\n \"project_id\": \"49e895da-15c6-4211-97df-65c547a59c22\",\n \"pipeline_id\": pipeline_id, # 84\n \"run_id\": 324 # Same as buildId\n })\n \n # Get failure analysis if needed\n failure_summary = await client.call_tool(\"get_pipeline_failure_summary\", {\n \"project_id\": \"49e895da-15c6-4211-97df-65c547a59c22\",\n \"pipeline_id\": pipeline_id,\n \"run_id\": 324\n })\n ```\n\n### Common Mistake to Avoid\n\n\u274c **Don't do this**: \n```python\n# This will fail - you can't guess the pipeline_id\nawait client.call_tool(\"get_pipeline_run\", {\n \"project_id\": \"49e895da-15c6-4211-97df-65c547a59c22\",\n \"pipeline_id\": 15, # Wrong! This is just a guess\n \"run_id\": 324\n})\n```\n\n\u2705 **Do this instead**:\n```python\n# First, get the build details to find the correct pipeline_id\nbuild_data = await client.call_tool(\"get_build_by_id\", {\n \"project_id\": \"49e895da-15c6-4211-97df-65c547a59c22\",\n \"build_id\": 324 # buildId from URL\n})\n\npipeline_id = build_data.data[\"definition\"][\"id\"] # Now you have the correct pipeline_id\n\n# Then use it for pipeline-specific operations\nawait client.call_tool(\"get_pipeline_run\", {\n \"project_id\": \"49e895da-15c6-4211-97df-65c547a59c22\", \n \"pipeline_id\": pipeline_id, # Correct pipeline_id\n \"run_id\": 324\n})\n```\n\n### Available Tools for Build/Pipeline Analysis\n\n- **`get_build_by_id`**: Get build details and extract pipeline information from a build/run ID\n- **`get_pipeline_run`**: Get detailed run information (requires both pipeline_id and run_id)\n- **`get_pipeline_failure_summary`**: Analyze failures with root cause analysis\n- **`get_failed_step_logs`**: Get logs for failed steps\n- **`get_pipeline_timeline`**: Get execution timeline\n- **`list_pipeline_logs`**: List all available logs\n- **`get_log_content_by_id`**: Get specific log content\n- **`run_pipeline_and_get_outcome`**: Run a pipeline and wait for completion with analysis \n",
"bugtrack_url": null,
"license": null,
"summary": "An MCP server for Azure DevOps pipelines.",
"version": "0.0.1",
"project_urls": {
"Documentation": "https://ado-mcp.readthedocs.io/",
"Homepage": "https://github.com/raboley/ado-mcp",
"Issues": "https://github.com/raboley/ado-mcp/issues",
"Repository": "https://github.com/raboley/ado-mcp"
},
"split_keywords": [
"azure-devops",
" mcp",
" model-context-protocol",
" ci-cd",
" pipelines",
" automation",
" devops",
" azure",
" llm",
" ai-tools"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e6ccbb044dc3478cd54dbe5a99a49a5af7b012a7b1886da23b16209a96a58697",
"md5": "3bdb39865246dc5ea3a7c3aa467ebe21",
"sha256": "b0308411d846f09ec4565b2b77437ef0b46866c390fda36117bea2339df5e5e1"
},
"downloads": -1,
"filename": "ado_mcp-0.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3bdb39865246dc5ea3a7c3aa467ebe21",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 126001,
"upload_time": "2025-07-27T18:47:39",
"upload_time_iso_8601": "2025-07-27T18:47:39.905630Z",
"url": "https://files.pythonhosted.org/packages/e6/cc/bb044dc3478cd54dbe5a99a49a5af7b012a7b1886da23b16209a96a58697/ado_mcp-0.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "518a417dea08486bb10151128fdd62ab4e328ecf27437900c68eacb46e0ad635",
"md5": "376316047b8d71cfdc073402fd1be5f0",
"sha256": "9111eff93f96267a3a8189cccfc0393dec7c149efd860f8ef3d662fc04512fe1"
},
"downloads": -1,
"filename": "ado_mcp-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "376316047b8d71cfdc073402fd1be5f0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 203029,
"upload_time": "2025-07-27T18:47:41",
"upload_time_iso_8601": "2025-07-27T18:47:41.663828Z",
"url": "https://files.pythonhosted.org/packages/51/8a/417dea08486bb10151128fdd62ab4e328ecf27437900c68eacb46e0ad635/ado_mcp-0.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-27 18:47:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "raboley",
"github_project": "ado-mcp",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ado-mcp"
}
JSON
