devops-mcp 1.8.0

An MCP server that gives LLMs your Azure DevOps: pipelines, repos, pull requests, work items, and more. 66 tools, read-only by default.

Runs over stdio, so it works with Claude Code, GitHub Copilot, Cursor, and any other MCP client.

Quick start

You don't start the server yourself — your MCP client launches it. Install uv (it provides uvx), run az login, then register the server.

Claude Code — .mcp.json in your project root:

{
  "mcpServers": {
    "devops-mcp": {
      "command": "uvx",
      "args": ["devops-mcp"],
      "env": {
        "AZDO_ORGANIZATION": "<your-org>",
        "AZDO_PROJECT": "<your-project>"
      }
    }
  }
}

VS Code / GitHub Copilot — .vscode/mcp.json, same thing under servers with an explicit type:

{
  "servers": {
    "devops-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["devops-mcp"],
      "env": {
        "AZDO_ORGANIZATION": "<your-org>",
        "AZDO_PROJECT": "<your-project>"
      }
    }
  }
}

Restart the client, then ask your agent to list my Azure DevOps projects. Reads work straight away; writes need a gate (below).

Configuration

Everything is set by environment variable. Nothing is hardcoded.

Authentication

Microsoft Entra ID OAuth 2.0 via azure-identity.

interactive prompts once. After that the token cache (encrypted by the OS secret store) makes restarts silent, until the refresh token expires. Two things worth knowing:

• On headless Linux with no secret store, the cache falls back to memory and the server logs a warning. AZDO_EPHEMERAL_TOKEN=true silences it.
• Two sessions signed in to different tenants share cache files and clobber each other. Give each a distinct AZDO_TOKEN_CACHE_PROFILE.

Security

Write and delete tools are off by default. They aren't registered, so the agent can't see them, let alone call them. Set AZDO_ALLOW_WRITE=true and AZDO_ALLOW_DELETE=true to opt in.

Deletes are recoverable by default. devops_delete_work_item sends the item to the recycle bin; destroy=true is opt-in per call, and Azure DevOps gates it behind a separate admin permission. devops_delete_query is always soft — restore with devops_update_query(undelete=true), though permissions on the item don't come back.

Attachment URLs are parsed, then thrown away. An <img src> from a work item description is untrusted input, so following it with a bearer token attached would leak that token. Instead the URL is validated (https, dev.azure.com or {org}.visualstudio.com, the attachment route, the right org), only the GUID and file name are kept, and the request is rebuilt against the resolved org. Rejections happen before a token is minted. A URL that fails is counted, never echoed back.

Uploads are images only, checked by bytes. devops_upload_work_item_attachment requires a .png/.jpg/.jpeg/.gif/.webp name and matching magic bytes, so id_rsa renamed to x.png is refused. AZDO_ATTACHMENT_ROOT restricts it further.

Secrets are never returned. Service connection authorization.parameters are filtered through an allowlist of non-secret fields; variable group secrets are dropped, as are non-secret variables with credential-shaped names. Withheld field names are reported so an agent knows a credential exists.

Stdout belongs to the MCP transport. All logs go to stderr. Don't redirect stdout.

Retries are safe by construction. 429 retries on any method; 502/503/504 retries only on reads, because a gateway error on a write may land after the write committed. Responses over 5 MB are refused with a hint to narrow the query.

Client setup

Every client launches the same stdio process; only the JSON wrapper differs. Claude and Cursor use mcpServers, VS Code uses servers plus "type": "stdio".

Keep these files out of source control — they can hold a client secret. Restart the client after editing; the write and delete gates are read once at startup.

Enabling writes. Add "AZDO_ALLOW_WRITE": "true" to the env block, and "AZDO_ALLOW_DELETE": "true" for deletes.

Service principal (CI/CD). Swap the env block for:

{
  "AZDO_AUTH_TYPE": "client_secret",
  "AZDO_TENANT_ID": "<your-tenant-id>",
  "AZDO_CLIENT_ID": "<your-client-id>",
  "AZDO_CLIENT_SECRET": "<your-client-secret>",
  "AZDO_ORGANIZATION": "<your-org>",
  "AZDO_PROJECT": "<your-project>"
}

Local checkout. Point the client at your clone — uv syncs the environment before launching, and --directory means the client's working directory doesn't matter:

{
  "command": "uv",
  "args": ["--directory", "/path/to/devops-mcp", "run", "devops-mcp"]
}

Two tenants on one host. Register one entry per tenant, each with its own AZDO_TENANT_ID and AZDO_TOKEN_CACHE_PROFILE (prod, dev, …). Each signs in once, then restarts silently as its own account. One entry already reaches any org you have access to — organization and project are per-call arguments — so add a second only for a different account or tenant.

Tools

66 tools across 9 domains. The gate column says when a tool is registered: default always, write under AZDO_ALLOW_WRITE=true, delete under AZDO_ALLOW_DELETE=true.

Pipelines (10)

Repositories (8)

Pull requests (17)

Work items (15)

Saved queries (7)

Address a query by GUID or by path — Shared Queries/Website team/All Bugs. The roots are Shared Queries and My Queries; neither can be renamed or moved here, because Azure DevOps allows it and it breaks path addressing for everything below.

To recover a deleted query: read the parent folder with devops_get_query(depth=1, include_deleted=true), take the child's GUID, then devops_update_query(query=<guid>, undelete=true). A deleted item answers to its GUID only — include_deleted on its path still returns 404.

Discovery (2)

Advanced Security (3)

Needs GitHub Advanced Security for Azure DevOps enabled on the repo.

Service connections (2)

Health is three separate signals: is_ready, is_disabled, and is_outdated (stored config no longer matches the real resource — usually an expired secret). A ready connection can still fail to authenticate.

Variable groups (2)

Notes

API versions. Pipelines, repos, discovery, work item schema, service connections, and variable groups use v7.1. PR tools, work item writes, and saved queries use v7.2-preview. Advanced Security uses v7.2-preview.1 on advsec.dev.azure.com. See the Azure DevOps REST API docs.

run_id and build_id are the same number. A Pipelines run ID is the Build API's buildId, so IDs from one API work in the other.

Reading logs cheaply. Try devops_get_run_timeline first — it often answers "why did it fail" with no log fetch at all. Then devops_search_run_log to grep. Only then devops_get_run_log_content, which pages rather than dumping.

Requires MCP Python SDK 2.0+. Releases up to 1.3.0 need SDK 1.x and won't start on 2.x — the SDK dropped mcp.server.fastmcp. Upgrade to 1.4.0 or later.

Development

uv sync                        # install
uv run pytest                  # tests (no network, no credentials)
uv run ruff check src tests    # lint
uv run python -m build         # build