adtk — Azure DevOps Toolkit

A dual-mode Go CLI & MCP server for Azure DevOps. Single binary, PAT-first auth, 14 MCP tools with 91 actions, 4 MCP prompts.

The most comprehensive Azure DevOps MCP server. A single Go binary — CLI for humans, MCP for AI agents.

Comparison: adtk vs Microsoft azure-devops-mcp

Features

• Dual-mode — Full CLI with table output + MCP server for AI agents
• 14 consolidated MCP tools with 91 actions covering every Azure DevOps domain
• 4 MCP prompts — sprint_summary, pr_review_digest, pipeline_health, release_readiness
• Git branch detection — Auto-detect work item IDs from branch names (e.g., feature/12345-description)
• Work item metrics — Cycle time, lead time, time-in-status computed from revision history
• PAT-first auth — Self-service Personal Access Tokens, no Azure AD admin approval
• Single binary — No Node.js, Python, or Docker required
• Response flattening — Strips _links and converts System.* fields to readable names
• Write protection — All mutations gated behind ADTK_ENABLE_WRITES=true
• Rate limiting — Built-in token bucket respecting Azure DevOps TSTU limits
• Token-optimized — AI agents get clean, concise payloads (40-60% fewer tokens)

Installation

go install

go install github.com/zach-snell/adtk/cmd/adtk@latest

Build from source

git clone https://github.com/zach-snell/adtk.git
cd adtk
./install.sh

Pre-built binaries

Download from the Releases page.

Quick Start

Authenticate

adtk auth
# Or use environment variables:
export AZURE_DEVOPS_ORG=myorg
export AZURE_DEVOPS_PAT=your-pat-here

CLI Usage

# Projects
adtk projects list
adtk projects get MyProject
adtk projects teams MyProject

# Work items
adtk work-items get 42
adtk work-items list -p MyProject

# Repositories
adtk repos list -p MyProject
adtk repos branches myrepo -p MyProject
adtk repos tree myrepo /src -p MyProject
adtk repos policies myrepo -p MyProject
adtk repos tags myrepo -p MyProject

# Pull requests
adtk pull-requests list myrepo -p MyProject
adtk pull-requests get myrepo 1

# Pipelines
adtk pipelines list -p MyProject
adtk pipelines runs 42 -p MyProject
adtk pipelines var-groups -p MyProject
adtk pipelines var-group 1 -p MyProject
adtk pipelines environments -p MyProject

# Iterations & boards
adtk iterations current -p MyProject
adtk boards list -p MyProject
adtk boards columns Stories -p MyProject

# Wiki
adtk wiki list -p MyProject
adtk wiki get ProjectWiki /Home -p MyProject

# Work item metrics
adtk work-items metrics 42 -p MyProject

# Work item auto-detect from git branch
adtk work-items get          # auto-detects work item ID from branch name

# Search
adtk search code "func main" -p MyProject
adtk search work-items "login bug" -p MyProject
adtk search wiql "SELECT [System.Id] FROM WorkItems WHERE [System.State] = 'Active'"
adtk search query "My Saved Queries/Active Bugs" -p MyProject

# Test plans
adtk test-plans list -p MyProject

# Security alerts
adtk security alerts myrepo -p MyProject

# Attachments
adtk attachments list 42 -p MyProject

# All commands support --json for raw output
adtk projects list --json

MCP Server

stdio mode (for AI agents)

adtk mcp

HTTP Streamable mode

adtk mcp --port 8080

MCP Client Configuration

Claude Desktop / Cursor / Claude Code:

{
  "mcpServers": {
    "adtk": {
      "command": "adtk",
      "args": ["mcp"],
      "env": {
        "AZURE_DEVOPS_ORG": "myorg",
        "AZURE_DEVOPS_PAT": "your-pat-here",
        "ADTK_ENABLE_WRITES": "true"
      }
    }
  }
}

Environment Variables

MCP Tools

adtk exposes 14 MCP tools with 91 actions and 4 MCP prompts:

MCP Prompts

Security

Write Protection

adtk is read-only by default. All create, update, delete, and trigger operations require:

export ADTK_ENABLE_WRITES=true

PAT Auth

Uses HTTP Basic Auth with empty username: Authorization: Basic base64(":" + pat). No Azure AD admin consent required.

Rate Limiting

Built-in token bucket rate limiter (30 tokens, refill 1/2s) prevents hitting Azure DevOps TSTU throttling limits.

Architecture

• Custom HTTP client — Direct REST API calls, no third-party SDK
• Multi-base-URL routing — dev.azure.com, vssps.dev.azure.com, almsearch.dev.azure.com, vsrm.dev.azure.com
• JSON Patch for work item writes — Content-Type: application/json-patch+json
• WIQL 2-step — Query IDs, then batch fetch fields (max 200 per request)
• Response flattener — System.Title → title, Microsoft.VSTS.Common.Priority → priority
• ETag concurrency — Wiki updates use If-Match headers for optimistic concurrency
• Team-scoped APIs — Iterations/boards use {project}/{team} URL routing

Development

# Build
go build -o adtk ./cmd/adtk

# Test
go test -race ./...

# Lint
golangci-lint run ./...

# Vulnerability check
govulncheck ./...

See the development guide for full details.

Documentation

Full documentation: zach-snell.github.io/adtk

License

Apache 2.0 — see LICENSE