Skip to main content
Glama
Sign In
ado-mcp-server

ado-mcp-server

by ms31376
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Azure DevOps MCP Server (Server & Services)

An MCP server that connects Claude (and other MCP clients) to Azure DevOps Server (on-premises: 2019, 2020, 2022) and Azure DevOps Services (cloud).

  • Uses your own Personal Access Token: you see exactly what your account can see.

  • Read-only by default. Write and delete tools are only loaded when you choose a higher access level.

  • Covers work items, test plans, repos, pull requests and pipelines.

Access levels

Level

What is enabled

read (default)

All search and read tools

write

+ create/update work items and bugs, links, comments, test cases, suites, PR comments, run pipelines

full

+ deletes (delete_work_item to the Recycle Bin, delete_test_case permanently)

Tools above your level are not registered at all, so the model cannot see or call them.

Related MCP server: Azure DevOps MCP Server

How changes are approved

Every write tool works in two steps:

  1. Called with preview=True (the default) it changes nothing and returns exactly what would happen, e.g. State: New -> Active, Priority: 2 -> 1.

  2. Only after you approve, it is called again with preview=False.

update_work_item also returns the current revision; passing it back as expected_revision makes the update fail if someone else changed the item in between.

On top of that, write tools are annotated readOnlyHint: false and delete tools destructiveHint: true, so your MCP client asks for permission before each call. Do not choose "Always allow" for write or delete tools.

Tools

Area

Read

Write (write)

Delete (full)

Connection

whoami, list_projects, list_teams, list_team_members

Work items

search_work_items, query_wiql, get_work_item, get_work_item_history, get_comments, list_work_item_types

create_work_item, create_bug, update_work_item, link_work_items, add_comment

delete_work_item

Test

search_test_cases, get_test_case, list_test_plans, list_test_suites, get_suite_test_results

create_test_case, add_test_cases_to_suite

delete_test_case

Boards

list_iterations, get_task_schedule

Repos

list_repositories, list_branches, browse_repository, get_file_content, list_commits, list_pull_requests, get_pull_request

add_pull_request_comment

Pipelines

list_pipelines, list_pipeline_runs, get_pipeline_run, get_pipeline_log

run_pipeline

Create a Personal Access Token

User settings → Personal access tokens → New token. Suggested scopes:

Scope

read

write / full

Work Items

Read

Read & Write

Test Management

Read

Read & Write

Code

Read

Read & Write (PR comments)

Build

Read

Read & Execute (run pipelines)

Project and Team

Read

Read

Use a short expiry and never share your PAT. Everything you do through this server is recorded in Azure DevOps under your name.

Install

Claude Desktop - one command

No Developer Mode needed. The script downloads the latest release and opens the installer in Claude Desktop; you only fill in the form.

Windows (PowerShell):

irm https://raw.githubusercontent.com/ms31376/ado-mcp-server/main/install.ps1 | iex

macOS (Terminal):

curl -fsSL https://raw.githubusercontent.com/ms31376/ado-mcp-server/main/install.sh | bash

Claude Desktop - manual

  1. Download the latest extension: https://github.com/ms31376/ado-mcp-server/releases/latest/download/ado-mcp-server.mcpb

  2. Double-click the downloaded file (or drag it onto the Claude Desktop window; dropping it into the chat box only attaches it to a message).

  3. Click Install and fill in the form.

To change settings later (for example the access level): open Claude Desktop Settings → Customize → Connectors (called Extensions in some versions), select Azure DevOps, change the settings, then turn the extension off and on (or restart Claude Desktop).

Claude Code

Works from any terminal (PowerShell, cmd, bash); you don't need to know where Claude Code is installed. One line:

claude mcp add --scope user azure-devops -e ADO_URL=https://server/Collection -e ADO_PAT=YOUR_PAT -e ADO_ACCESS_LEVEL=read -- uvx --from git+https://github.com/ms31376/ado-mcp-server ado-mcp-server

Then run /mcp inside Claude Code to check the connection.

Other MCP clients (VS Code, Cursor, ...)

{
  "mcpServers": {
    "azure-devops": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/ms31376/ado-mcp-server", "ado-mcp-server"],
      "env": {
        "ADO_URL": "https://dev.azure.com/YourOrg",
        "ADO_PAT": "...",
        "ADO_PROJECT": "MyProject",
        "ADO_ACCESS_LEVEL": "read"
      }
    }
  }
}

This runs the code straight from GitHub; uvx downloads it on first start. A PyPI package (uvx ado-mcp-server) is planned.

All methods need uv except the Claude Desktop extension, which manages Python by itself.

Configuration

Variable

Default

Description

ADO_URL

(required)

https://server/Collection or https://dev.azure.com/Org

ADO_PAT

(required)

Personal Access Token

ADO_PROJECT

Default project

ADO_TEAM

<project> Team

Default team for iteration tools

ADO_ACCESS_LEVEL

read

read, write or full

ADO_API_VERSION

7.0

7.0 Server 2022 / cloud, 6.0 Server 2020, 5.0 Server 2019

ADO_IGNORE_PROXY

false

Ignore HTTP(S)_PROXY (useful for internal servers)

ADO_VERIFY_SSL

true

SSL verification

ADO_CA_BUNDLE

Path to a company CA certificate (.pem)

Troubleshooting

Symptom

Fix

401 Unauthorized

The PAT is wrong, expired or missing a scope. Copy it again without spaces.

Timeouts with an internal server

A proxy/VPN app is in the way: enable Ignore system proxy (ADO_IGNORE_PROXY=true).

"The server returned an HTML page"

Wrong server URL, or a sign-in page in between. Use the collection URL, e.g. https://server/DefaultCollection.

SSL certificate error

Set your company CA certificate (ADO_CA_BUNDLE).

Tool count did not change after changing the access level

Turn the extension off and on, or restart Claude Desktop. Check with whoami.

Claude says no Azure DevOps tools are connected

Make sure the chat is in the Claude Desktop app (not the browser) and the extension is enabled in the chat's tools menu.

Development

uv run --group dev pytest -q             # tests
uv run mcp dev server/main.py            # MCP Inspector
npx @anthropic-ai/mcpb pack . ado-mcp-server.mcpb

License

MIT

Available Tools

28 tools
browse_repositoryB
Read-only

List files and folders in a repository folder (one level).

Inputs: repository (required), path, branch, project. Returns: result

get_commentsC
Read-only

Comments (Discussion) of a work item.

Inputs: work_item_id (required), top. Returns: result

get_file_contentC
Read-only

Content of a text file in a repository (truncated to max_chars).

Inputs: path (required), repository (required), branch, project, +1 more.

get_pipeline_logA
Read-only

Log of a run. Without log_id, returns the last lines of every failed step. (log_id values come from get_pipeline_run.)

Inputs: build_id (required), log_id, project, tail_lines. Returns: result

get_pipeline_runB
Read-only

Details of one run, including failed or warning steps with their error messages.

Inputs: build_id (required), project.

get_pull_requestB
Read-only

Details of a pull request: description, reviewers and votes, linked work items.

Inputs: pull_request_id (required), project.

get_suite_test_resultsB
Read-only

Test points of a suite: each test case per configuration with tester and last outcome (Passed / Failed / Blocked / NotApplicable / NotRun), plus a summary count.

Inputs: plan_id (required), suite_id (required), project.

get_task_scheduleC
Read-only

Scheduling view: start/target dates, estimates, remaining work, overdue flags and remaining work per person.

current_iteration=True uses the team's current sprint. work_item_type: one or several separated by commas, e.g. "Task, Bug".

Inputs: top, team, project, assigned_to, +4 more.

get_test_caseC
Read-only

One test case with its parsed steps (action / expected result).

Inputs: test_case_id (required).

get_work_itemB
Read-only

Full details of one work item: description, repro steps, acceptance criteria, scheduling fields and links (parent, children, related, tested by, commits, PRs).

Inputs: work_item_id (required).

get_work_item_historyB
Read-only

Change history of a work item: who changed which fields, from what to what.

Inputs: work_item_id (required), top. Returns: result

list_branchesC
Read-only

Branches of a repository; name_filter matches the start of the branch name.

Inputs: repository (required), project, name_filter. Returns: result

list_commitsB
Read-only

Recent commits of a repository, optionally for a branch, author or file/folder path.

Inputs: repository (required), top, path, author, +2 more. Returns: result

list_iterationsC
Read-only

Team iterations (sprints) with start/finish dates. timeframe: optional filter "past", "current" or "future".

Inputs: team, project, timeframe. Returns: result

list_pipeline_runsB
Read-only

Recent runs (builds), newest first. status: inProgress, completed, notStarted, ... result: succeeded, failed, canceled, partiallySucceeded.

Inputs: top, branch, result, status, +2 more. Returns: result

list_pipelinesB
Read-only

Pipelines (build definitions) of a project; name_filter supports * wildcards.

Inputs: project, name_filter. Returns: result

list_projectsB
Read-only

Projects the PAT can see.

Inputs: no named parameters. Returns: result

list_pull_requestsB
Read-only

Pull requests of a project (or one repository). status: active, completed, abandoned or all. created_by: part of a name.

Inputs: top, status, project, created_by, +2 more. Returns: result

list_repositoriesB
Read-only

Git repositories (of one project, or of all visible projects if no project is set).

Inputs: project. Returns: result

list_team_membersD
Read-only

Members of a team.

Inputs: team (required), project. Returns: result

list_teamsC
Read-only

Teams of a project (team names are used by iteration and schedule tools).

Inputs: project. Returns: result

list_test_plansC
Read-only

Test plans of a project.

Inputs: project, active_only. Returns: result

list_test_suitesC
Read-only

Suites of a test plan, with parent suite ids to rebuild the tree.

Inputs: plan_id (required), project. Returns: result

list_work_item_typesC
Read-only

Work item types of a project (Bug, Task, User Story, Feature, Test Case, ...).

Inputs: project. Returns: result

query_wiqlB
Read-only

Run a read-only WIQL query (SELECT ... FROM WorkItems / WorkItemLinks ...) for searches the other tools cannot express. Returns work item summaries.

Inputs: wiql (required), top, project. Returns: result

search_test_casesB
Read-only

Search Test Case work items by title text, state, owner ("@me"), tags, area or iteration.

Inputs: top, tags, text, state, +4 more. Returns: result

search_work_itemsA
Read-only

Search work items of any type.

text: matches the title, or the ID if numeric. work_item_type: one type or several separated by commas, e.g. "Bug, Task". assigned_to / created_by: part of a name, or "@me". tags: one tag or several separated by ";" (all must match). iteration_path / area_path: includes children, e.g. "MyProject\Sprint 12".

Inputs: top, tags, text, state, +8 more. Returns: result

whoamiA
Read-only

Check the connection: the signed-in user (owner of the PAT), server URL, access level of this extension and which tools are enabled.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    C2.6/5.0

    Scored across 28 tools

    Disambiguation4/5

    Most tools are clearly separated by Azure DevOps subdomain and action: work items, pipelines, repositories, tests, teams. There is minor overlap between search_work_items, search_test_cases, and query_wiql as multiple search entry points, but the descriptions generally make the intended use clear.

    Naming Consistency4/5

    The set uses a consistent snake_case verb_noun pattern such as get_work_item, list_pipeline_runs, and search_test_cases. whoami is the only meaningful deviation, but it is a conventional identity command and remains understandable.

    Tool Count2/5

    At 28 tools, the surface is heavy and exceeds the well-scoped range, even for a broad platform like Azure DevOps. While many tools serve distinct domains, the total volume increases selection burden for an agent.

    Completeness2/5

    The surface is almost entirely read-only: there are no create, update, delete, queue-pipeline, or PR mutation operations. Even if read-only inspection is intentional, notable read gaps remain such as PR file/thread details and repository code search.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers