How do I use ado-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ado-mcp list my Azure DevOps projects" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

ado-mcp

by raboley

Overview Schema Related Servers Score Discussions

Python

Remote

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 | 🚀 Quick Start | 🛠️ API Reference

Prerequisites

You'll need these installed before setting up the MCP server:

UV (Python package runner):

# Install UV (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

Azure CLI with DevOps extension:

# 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

Authenticate with Azure DevOps:
```
# 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.

Test the setup:

# Test that everything works
uvx ado-mcp --help

Installation

macOS Configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "ado-mcp": {
      "command": "uvx",
      "args": ["ado-mcp"],
      "env": {
        "ADO_ORGANIZATION_URL": "https://dev.azure.com/YourOrg"
      }
    }
  }
}

Windows Configuration (%APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "ado-mcp": {
      "command": "uvx",
      "args": ["ado-mcp"],
      "env": {
        "ADO_ORGANIZATION_URL": "https://dev.azure.com/YourOrg"
      }
    }
  }
}

Restart Claude Desktop to load the MCP server.

Note: uvx automatically downloads and runs the latest version. No manual installation needed!

Add the MCP server:

# 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

Verify the installation:

# List configured MCP servers
claude mcp list

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.

Go to: Settings → Cursor Settings → MCP → Add new global MCP server

Configuration:

{
  "name": "ado-mcp",
  "command": "uvx",
  "args": ["ado-mcp-raboley"],
  "env": {
    "ADO_ORGANIZATION_URL": "https://dev.azure.com/YourOrg"
  }
}

Save and restart Cursor.

Install Continue extension from VS Code marketplace.

Configure in ~/.continue/config.json:

{
  "models": [...],
  "mcpServers": [
    {
      "name": "ado-mcp",
      "command": "uvx",
      "args": ["ado-mcp"],
      "env": {
        "ADO_ORGANIZATION_URL": "https://dev.azure.com/YourOrg"
      }
    }
  ]
}

Restart VS Code to load the configuration.

Open Zed settings (Cmd+, on macOS, Ctrl+, on Linux/Windows).

Add to MCP settings:

{
  "language_models": {
    "mcp_servers": {
      "ado-mcp": {
        "command": "uvx",
        "args": ["ado-mcp"],
        "env": {
          "ADO_ORGANIZATION_URL": "https://dev.azure.com/YourOrg"
        }
      }
    }
  }
}

Restart Zed to apply changes.

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

If you prefer not to use Azure CLI, you can set environment variables directly:

Set environment variables:

export AZURE_DEVOPS_EXT_PAT="your-personal-access-token"
export ADO_ORGANIZATION_URL="https://dev.azure.com/YourOrg"

Configure with environment variables:

{
  "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.

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

Install Dependencies:
```
task install
```
Set up Authentication: The MCP server supports multiple authentication methods (in order of precedence):
Option 1: Personal Access Token (PAT)
Environment Variable Method:
```
task setup-env
```
This creates a .env file with your Personal Access Token (PAT) and other necessary variables.
Direct Configuration:
```
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:
```
# 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

Configure environment:

cp .env.example .env  # Edit with your Azure DevOps details

Provision test environment:

task ado-up  # Creates Azure DevOps project and infrastructure

Run tests:
```
task test
```

Clean up:

task ado-down  # Destroys the test environment

Test Commands

Run all tests (parallel):
```
task test
```

Run single test:

task test-single TEST_NAME=tests/test_example.py::test_function_name

Test coverage:
```
task coverage
```

📚 Detailed Testing Setup Guide

Setup Azure DevOps CLI (for Azure DevOps CLI commands):
```
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:
```
task run
```
Inspect the MCP Server:
```
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:

# 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:

# 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:

# 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:

# 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:

Install Dependencies:
```
task install
```
Set up Authentication: The MCP server supports multiple authentication methods (in order of precedence):
Option 1: Personal Access Token (PAT)
Environment Variable Method:
```
task setup-env
```
This creates a .env file with your Personal Access Token (PAT) and other necessary variables.
Direct Configuration:
```
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:
```
# 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

Configure environment:

cp .env.example .env  # Edit with your Azure DevOps details

Provision test environment:

task ado-up  # Creates Azure DevOps project and infrastructure

Run tests:
```
task test
```

Clean up:

task ado-down  # Destroys the test environment

Test Commands

Run all tests (parallel):
```
task test
```

Run single test:

task test-single TEST_NAME=tests/test_example.py::test_function_name

Test coverage:
```
task coverage
```

📚 Detailed Testing Setup Guide

Setup Azure DevOps CLI (for Azure DevOps CLI commands):
```
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:
```
task run
```
Inspect the MCP Server:
```
task inspect
```

Documentation

View documentation locally:
```
task docs-serve
```
This automatically builds the docs and serves them at http://localhost:8000

The documentation is built with Sphinx and hosted on Read the Docs.

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:

Extract URL components:
- Organization: RussellBoley
- Project: ado-mcp
- Build/Run ID: 324 (from buildId parameter)

Use get_build_by_id to find the pipeline:

# 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"

Then use pipeline-specific tools:

# 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:

# 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:

# 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

This server cannot be installed

license - permissive license

quality - not tested

maintenance

How are these scores calculated?

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
open source
OpenAI
Tool Definition Quality Score (TDQS)
By punkpeye on April 3, 2026.
mcp
The Hackers Who Tracked My Sleep Cycle
By punkpeye on March 26, 2026.
security

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/raboley/ado-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

ADO MCP

Prerequisites

Installation

Features

🔧 Pipeline Operations

🔍 Smart Search & Discovery

📊 Logs & Debugging

🔐 Flexible Authentication

⚡ Performance & Caching

Development Setup

Option 1: Personal Access Token (PAT)

Option 2: Azure CLI Authentication (Recommended)

Testing

Quick Test Setup

Test Commands

Usage

Getting Started

Basic Operations

Pipeline Analysis

Advanced Usage

Troubleshooting

Authentication Issues

Installation Issues

Development Setup

Option 1: Personal Access Token (PAT)

Option 2: Azure CLI Authentication (Recommended)

Testing

Quick Test Setup

Test Commands

Usage

Documentation

Working with Azure DevOps URLs

Understanding Azure DevOps URL Structure

Getting Pipeline Information from Build URLs

Common Mistake to Avoid

Available Tools for Build/Pipeline Analysis

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API