Azure DevOps MCP — Claude Code Integration

Connect Claude Code to Azure DevOps for AI-assisted work item management, repo browsing, PR creation, release inspection, and complete commit lifecycle tracing.

---

What This Does

Ask Claude Code things like:

"Show me all active bugs assigned to me in Sprint 42"
"Create a bug: login fails on Safari with priority 1"
"Trace commit abc1234 — what PR, build, and release did it go through?"
"What was shipped in the last release of xyz pipeline? Show me every commit and work item."
"Raise a PR from feature/auth-fix to main with these reviewers"
"What tickets drove this release? Show approvals."

---

Tool Inventory (20 tools)

Work Items (5)

Tool	Description
list_work_items	Query with filters: type, state, sprint, assignee, tag, priority, or raw WIQL
get_work_item	Full details: description, comments, linked items, relations
create_work_item	Create bug/task/story/epic with all fields including acceptance criteria
update_work_item	Update state, assignee, priority, add comments
search_work_items	Full-text search across titles and descriptions

Repositories (7)

Tool	Description
list_repositories	All repos with size, default branch, URLs
get_repository	Single repo with branch stats
list_branches	Branches with latest commit info, ahead/behind counts
list_commits	Commits filtered by branch, author, date, message
get_commit	Full commit: author, date, all changed files
get_file_content	Read any file at any branch/commit
get_commit_diff	Changed files for a commit with change type (add/edit/delete)

Pull Requests (4)

Tool	Description
list_pull_requests	Filter by status, creator, branch, reviewer (all repos or one)
get_pull_request	Full PR: reviewers+votes, commits, linked work items, comment threads, CI status
create_pull_request	Create PR with reviewers, work item links, auto-complete, merge strategy
get_pr_comments	All review threads with file/line context

Releases & Pipelines (4)

Tool	Description
list_release_definitions	All classic release pipelines
get_last_release	Latest release with artifacts, environments, approvals, work items deployed
get_release_details	Specific release by ID
list_pipeline_runs	YAML pipeline runs with status/result/branch
get_pipeline_run_details	Stages, jobs, failed task logs
list_environments	Deployment environments and their approval policies

Journeys (3) — the power tools

Tool	Description
trace_commit_journey	Commit → PR → Build → Release — complete lifecycle of one commit
trace_work_item_journey	Ticket → PRs → Commits → Builds → Releases — when and how was this shipped?
trace_release_journey	Release → Commits + Work Items + Approvals — what exactly did we ship?

---

Setup

1. Install Dependencies & Build

cd azure-devops-mcp
npm install
npm run build

2. Generate Azure DevOps PAT

Go to dev.azure.com/YOUR_ORG → User Settings (avatar) → Personal Access Tokens → New Token

Required scopes:

• Work Items: Read & Write
• Code: Read & Write
• Build: Read & Execute
• Release: Read & Execute
• Project and Team: Read

3. Set Environment Variables

# Add to ~/.zshrc or ~/.bashrc
export AZURE_DEVOPS_ORG_URL=https://dev.azure.com/YOUR_ORG
export AZURE_DEVOPS_PAT=your_pat_token_here
export AZURE_DEVOPS_PROJECT=YourProjectName

4. The .mcp.json is Already Configured

The .mcp.json at project root uses ${VAR} to expand from your environment — safe to commit, no secrets.

5. Verify

source ~/.zshrc
claude
# Inside Claude Code:
/mcp
# Should show: azure-devops (connected) with 20 tools

---

Flow Diagrams

Request Flow

User: "Trace commit abc1234"
        │
        ▼
┌──────────────────┐
│   Claude AI      │  selects tool: trace_commit_journey
│   Model          │  args: { commitId: "abc1234" }
└────────┬─────────┘
         │ tool call (JSON-RPC 2.0 over stdio)
         ▼
┌──────────────────────────────────┐
│   Azure DevOps MCP Server        │
│   (node azure-devops-mcp/dist/)  │
│                                  │
│   1. getCommit(abc1234)          │
│   2. getPullRequests() ──────────┼─► filter by commit
│   3. getBuilds(commitId) ────────┼─► CI runs
│   4. getReleases() ──────────────┼─► match build artifacts
│   5. getWorkItems(ids) ──────────┼─► linked tickets
│                                  │
│   Stitch into journey object     │
└────────┬─────────────────────────┘
         │ JSON result
         ▼
┌──────────────────┐
│   Claude AI      │  formats as readable narrative
│   Model          │
└────────┬─────────┘
         │
         ▼
  User sees complete commit lifecycle

Commit Journey — Data Flow

                    COMMIT abc1234
                          │
          ┌───────────────┼───────────────┐
          │               │               │
          ▼               ▼               ▼
   Git API           Build API       Commit message
   getPullRequests   getBuilds       regex: #1234
   (search commits)  (sourceVersion)
          │               │               │
          ▼               ▼               ▼
       PR #42          Build #891      WI #1234
          │               │
          ▼               ▼
   getPRWorkItems    getBuildTimeline
   getPRCommits      getBuildWorkItems
          │               │
          ▼               ▼
    WI #567, #890    Stages/Jobs/Logs
                          │
                          ▼
                    Release API
                    getReleases
                    (match artifact buildId)
                          │
                          ▼
                     Release v2.4
                          │
                    ┌─────┴──────┐
                    ▼            ▼
                Staging      Production
                [deployed]   [approved by Sam]

    All data assembled into timeline_summary:
    [COMMIT] abc1234 "fix: login timeout" by Alice
    [PR #42] "Fix auth timeout" feature/fix -> main [completed]
       Reviewer: Bob: approved
    [BUILD #891] pipeline: CI-main result: succeeded
       Stage: Build [succeeded]
       Stage: Test [succeeded]
    [RELEASE] v2.4 pipeline: prod-deploy status: succeeded
       Env: Staging: succeeded deployed: 2026-03-15
       Env: Production: succeeded deployed: 2026-03-16
    [WORK ITEMS LINKED]:
       #1234 [Bug] "Login times out after 5 min" [Resolved]
       #567  [Task] "Add session refresh logic" [Closed]

Work Item Journey

    TICKET #1234 "Login timeout"
          │
          ▼
    witClient.getWorkItem(1234)
    → relations[] contains pullRequest links
          │
          ├─► PR IDs extracted from relations
          │         │
          │         ▼
          │   gitClient.getPullRequests()
          │   → match prIds
          │         │
          │         ▼
          │     PR #42, PR #51
          │         │
          │         ▼
          │   getPullRequestCommits()
          │   → commit SHAs
          │         │
          ▼         ▼
      buildClient.getBuilds(commitId)
      → Build #891, #892
          │
          ▼
      rmClient.getReleases()
      → getReleaseWorkItemsRefs()
      → match workItemId == 1234
          │
          ▼
      Release v2.4 contains #1234
          │
      environments: Staging ✓ Production ✓

    Timeline:
    [WORK ITEM #1234] [Bug] "Login timeout" State: Resolved
    [PR #42]  "Fix auth timeout"  [completed]  Mar 14 -> Mar 15
    [BUILD #891]  CI-main  result: succeeded
    [RELEASED]  v2.4  [succeeded]  Mar 16
       Env: Staging: succeeded
       Env: Production: succeeded

Release Journey

    "What shipped in last release of prod-deploy?"
          │
          ▼
    getReleaseDefinitions → find "prod-deploy"
          │
          ▼
    getReleases(definitionId, top=1) → Release v2.4
          │
          ▼
    getRelease(v2.4.id)
          │
    ┌─────┴──────────────────┐
    │                        │
    ▼                        ▼
artifacts[]              environments[]
  alias: WebApp            Staging
  buildId: 891               status: succeeded
  branch: main               preApprovals: [auto]
  commit: abc1234            postApprovals: [auto]
    │                      Production
    ▼                        status: succeeded
getBuildChanges(891)         preApprovals:
→ [abc1234, def5678,           approver: Sam
   ghi9012, ...]               on: 2026-03-16
                               comments: "LGTM"
    │
    ▼
getReleaseWorkItemsRefs(v2.4.id)
→ [#1234, #567, #890, #1101]
    │
    ▼
getWorkItems([ids])
→ Bug #1234: Login timeout [Resolved]
   Task #567: Session refresh [Closed]
   Story #890: Remember me [Closed]
   Bug #1101: Dark mode flash [Resolved]

    Timeline:
    [RELEASE] v2.4  pipeline: prod-deploy  [succeeded]
       Created by: CI Bot  on 2026-03-16
    [COMMITS INCLUDED] (12):
       abc1234  "fix: login timeout"  by Alice
       def5678  "feat: remember me"   by Bob
       ...
    [WORK ITEMS SHIPPED] (4):
       #1234 [Bug]   "Login timeout"    [Resolved]
       #567  [Task]  "Session refresh"  [Closed]
       ...
    [DEPLOYMENTS]:
       Staging: succeeded
       Production: succeeded
         Approved by Sam on 2026-03-16T14:23:00

PR Creation Flow

User: "Raise a PR from feature/auth-fix to main with Bob as reviewer"
        │
        ▼
Claude calls: create_pull_request
  repoName: "food-limit-api"
  sourceBranch: "feature/auth-fix"
  targetBranch: "main"
  title: "Fix auth timeout issue"
  reviewers: ["bob@company.com"]
  workItemIds: [1234]
        │
        ▼
MCP Server:
  gitClient.getRepositories() → find repo
  gitClient.createPullRequest({
    sourceRefName: "refs/heads/feature/auth-fix",
    targetRefName: "refs/heads/main",
    reviewers: [{uniqueName: "bob@company.com"}],
    workItemRefs: [{id: "1234"}],
    isDraft: false
  })
        │
        ▼
Azure DevOps creates PR #43
        │
        ▼
Claude reports:
  PR #43 created: "Fix auth timeout issue"
  feature/auth-fix -> main
  Reviewer: Bob
  Work item #1234 linked
  URL: dev.azure.com/.../pullrequest/43

---

Project Structure

azure-devops-mcp/
├── src/
│   ├── index.ts              # MCP server, tool registry, stdio transport
│   ├── client.ts             # AzDO client factory (dev + vsrm endpoints)
│   └── tools/
│       ├── workItems.ts      # list, get, create, update, search
│       ├── repos.ts          # list, browse, commits, file content, diff
│       ├── pullRequests.ts   # list, get, create, comments
│       ├── releases.ts       # classic releases + YAML pipeline runs
│       └── commitJourney.ts  # trace_commit_journey, trace_work_item_journey, trace_release_journey
├── package.json
├── tsconfig.json
└── dist/                     # compiled output (after npm run build)

---

Security

• .mcp.json uses ${VAR} — safe to commit, no secrets in git
• Each developer sets their own PAT in ~/.zshrc — never shared
• PATs should be scoped minimally (only the permissions listed above)
• Rotate PATs every 90 days or when team members leave

# Verify your PAT works
curl -u ":$AZURE_DEVOPS_PAT" \
  "$AZURE_DEVOPS_ORG_URL/_apis/projects?api-version=7.0"

---

Troubleshooting

Problem	Fix
/mcp shows azure-devops as disconnected	Run npm run build in azure-devops-mcp/, check env vars are set
401 Unauthorized	PAT expired or wrong — regenerate at dev.azure.com
403 Forbidden	PAT missing a scope — check the scope list above
"Project not found"	AZURE_DEVOPS_PROJECT must match exactly (case-sensitive)
Release tools return empty	Classic release pipeline only — if you use YAML pipelines use list_pipeline_runs instead
Commit journey shows no releases	Releases must have the build as an artifact and be in the same org