@kodessa-software/azdo-mcp

MCP server that gives Claude Code direct access to Azure DevOps — work items, repos, pull requests, pipelines and code search. No more copy-pasting ticket descriptions or switching browser tabs.

Requirements

• Node.js 20+
• An Azure DevOps organisation (cloud, dev.azure.com)
• A Personal Access Token with the scopes listed below

Installation

Via npx (no global install)

Add to your .mcp.json (or run claude mcp add):

{
  "mcpServers": {
    "azdo": {
      "command": "npx",
      "args": ["-y", "@kodessa-software/azdo-mcp"],
      "env": {
        "AZURE_DEVOPS_ORG": "your-org-name",
        "AZURE_DEVOPS_PAT": "${AZURE_DEVOPS_PAT}"
      }
    }
  }
}

Set AZURE_DEVOPS_PAT in your shell environment (e.g. ~/.zshrc or .env):

export AZURE_DEVOPS_PAT=your_token_here

PAT setup

1. Go to https://dev.azure.com → your avatar (top right) → Personal access tokens
2. Click New Token
3. Set the following scopes (minimum for full MVP functionality):

| Scope | Why | |---|---| | Work Items (Read & write) | Get, create, update work items | | Code (Read & write) | Read repos, manage PRs | | Build (Read & execute) | Run and monitor pipelines | | Project and team (Read) | List projects |

You can restrict scopes to read-only if you only need to query.

Use cases

1. Context ophalen voor een ticket

Werk aan AB#1234 — geef me een samenvatting en de acceptatiecriteria.

Claude calls azdo_workitem_get and returns title, description, acceptance criteria, state, linked PRs.

2. PR review

Review PR #42 in repo azdo-mcp en geef aandachtspunten.

Claude calls azdo_pr_get, azdo_pr_threads_list, and summarises the changes and open comments.

3. PR aanmaken

Maak een PR aan van feat/fase-1a naar main voor de work items tools.

Claude writes the PR description and calls azdo_pr_create.

4. Pipeline status checken

Is de main pipeline groen?

Claude calls azdo_pipeline_runs_list for the last run on main.

5. Codesearch

Zoek op useDebounce in alle repos en laat zien waar het al bestaat.

Claude calls azdo_search_code and returns file paths + snippets.

Available tools

Projects

| Tool | Description | |---|---| | azdo_ping | Smoke test — returns "pong" | | azdo_projects_list | List all projects in the org | | azdo_project_get | Get a project by name or ID | | azdo_project_create | Create a new project (async, polls until ready) | | azdo_project_update | Update project name, description, or visibility | | azdo_project_delete | Delete a project by ID |

Teams

| Tool | Description | |---|---| | azdo_teams_list | List all teams in a project | | azdo_team_get | Get a team by name or ID | | azdo_team_members_list | List members of a team | | azdo_team_create | Create a new team |

Work Items

| Tool | Description | |---|---| | azdo_workitem_get | Get a work item by ID | | azdo_workitems_query | Run a WIQL query | | azdo_workitem_create | Create a new work item | | azdo_workitem_update | Update fields on a work item | | azdo_workitem_comment_add | Add a discussion comment | | azdo_workitem_comments_list | List discussion comments | | azdo_workitem_delete | Delete a work item | | azdo_workitem_link_add | Add a relation link between work items | | azdo_workitem_link_remove | Remove a relation link | | azdo_workitems_batch_get | Get multiple work items by ID list |

Agile — Iterations & Sprints

| Tool | Description | |---|---| | azdo_iterations_list | List all iterations for a team | | azdo_current_sprint | Get the current sprint for a team | | azdo_iteration_get | Get a single iteration by ID | | azdo_iteration_workitems | Get work items in an iteration | | azdo_iteration_capacity | Get team member capacity for an iteration | | azdo_classification_nodes_get | Get classification node tree (areas/iterations) | | azdo_iteration_create | Create a new iteration node | | azdo_iteration_team_assign | Assign an iteration to a team |

Agile — Backlogs

| Tool | Description | |---|---| | azdo_backlogs_list | List all backlogs for a team | | azdo_backlog_get | Get a single backlog | | azdo_backlog_workitems | List work items in a backlog | | azdo_backlog_configuration | Get backlog configuration |

Agile — Boards / Kanban

| Tool | Description | |---|---| | azdo_boards_list | List boards for a team | | azdo_board_get | Get a board by ID | | azdo_board_columns | Get columns of a board | | azdo_board_rows | Get swimlanes (rows) of a board | | azdo_board_cards | Get cards (work items) on a board | | azdo_board_card_update | Update card settings on a board |

Git

| Tool | Description | |---|---| | azdo_repos_list | List repos in a project | | azdo_repo_get | Get repo details | | azdo_branches_list | List branches | | azdo_commits_list | List recent commits | | azdo_file_get | Read file content at a branch or commit | | azdo_tags_list | List tags | | azdo_file_create_or_update | Create or update a file via a push | | azdo_branch_create | Create a new branch | | azdo_diff_branches | Get diff between two branches |

Pull Requests

| Tool | Description | |---|---| | azdo_prs_list | List pull requests | | azdo_pr_get | Get PR details | | azdo_pr_create | Create a PR | | azdo_pr_threads_list | Read review threads | | azdo_pr_comment_add | Add a comment to a PR | | azdo_pr_update | Update PR title, description, or target branch | | azdo_pr_reviewer_add | Add a reviewer to a PR | | azdo_pr_vote | Vote on a PR (approve / reject / wait for author) | | azdo_pr_complete | Complete (merge) a PR | | azdo_pr_abandon | Abandon a PR |

Pipelines & Builds

| Tool | Description | |---|---| | azdo_pipelines_list | List pipeline definitions | | azdo_pipeline_get | Get pipeline details | | azdo_pipeline_run | Trigger a pipeline run | | azdo_pipeline_runs_list | List runs for a pipeline | | azdo_pipeline_run_get | Get a specific run status | | azdo_builds_list | List builds (classic Build API) | | azdo_pipeline_run_logs | Fetch build logs | | azdo_build_cancel | Cancel an in-progress build |

Releases

| Tool | Description | |---|---| | azdo_releases_list | List releases in a project | | azdo_release_get | Get release details including environments | | azdo_release_create | Create a release from a definition | | azdo_release_stage_approve | Approve a pending stage |

Search

| Tool | Description | |---|---| | azdo_search_code | Full-text code search across all repos | | azdo_search_workitems | Full-text work item search |

Saved Queries

| Tool | Description | |---|---| | azdo_queries_list | List saved queries | | azdo_query_get | Get a query by ID | | azdo_query_create | Create a new saved query | | azdo_query_update | Update a saved query | | azdo_query_run | Run a saved query by ID | | azdo_query_delete | Delete a saved query |

Delivery Plans

| Tool | Description | |---|---| | azdo_plans_list | List delivery plans | | azdo_plan_get | Get a delivery plan | | azdo_plan_deliverytimeline | Get delivery timeline for a plan | | azdo_plan_create | Create a new delivery plan |

Wiki

| Tool | Description | |---|---| | azdo_wikis_list | List wikis in a project | | azdo_wiki_get | Get wiki details | | azdo_wiki_page_get | Read a wiki page | | azdo_wiki_page_create_or_update | Create or update a wiki page | | azdo_wiki_search | Full-text search across wikis | | azdo_wiki_create | Create a new wiki | | azdo_wiki_page_delete | Delete a wiki page | | azdo_wiki_page_move | Move/rename a wiki page |

Test Plans

| Tool | Description | |---|---| | azdo_test_plans_list | List test plans in a project | | azdo_test_plan_get | Get a test plan by ID | | azdo_test_runs_list | List test runs | | azdo_test_run_get | Get a specific test run | | azdo_test_results_list | List test results for a run |

Configuration

| Variable | Required | Default | Description | |---|---|---|---| | AZURE_DEVOPS_ORG | ✅ | — | Organisation name (from dev.azure.com/<org>) | | AZURE_DEVOPS_PAT | ✅ | — | Personal Access Token | | LOG_LEVEL | — | warn | trace / debug / info / warn / error | | AZURE_DEVOPS_RATE_LIMIT | — | 10 | Max requests per second |

Troubleshooting

"PAT is invalid or expired" Generate a new token at https://dev.azure.com → User Settings → Personal access tokens.

"Access denied" Check that your PAT includes the required scopes listed in the PAT setup section above.

"Resource not found" Verify the project name and that the resource (work item ID, repo name, etc.) exists in your organisation.

Server doesn't appear in Claude Code Run npx @kodessa-software/azdo-mcp manually in your terminal to see startup errors. Check that AZURE_DEVOPS_ORG and AZURE_DEVOPS_PAT are set.

Development

git clone https://github.com/K-dessa/azdo-mcp
cd azdo-mcp
npm install
npm run dev          # start in dev mode with tsx
npm test             # run tests
npm run test:coverage
npm run lint
npm run typecheck

See CONTRIBUTING.md for branching and commit conventions.

License

MIT — see LICENSE