Azure DevOps MCP Server — Setup
This guide sets up the official Microsoft @azure-devops/mcp server. Once configured, you can manage Azure DevOps boards, work items, repos, pull requests, and pipelines directly from a Claude session — no context-switching to the ADO web UI. The steps below cover Claude Code; a Claude Desktop variant is included further down.
The server runs locally over stdio and authenticates as you, using your Azure CLI login. There is no PAT to create or store.
The Azure CLI (az) is a hard dependency — the ADO MCP server authenticates exclusively through your az login session. Without the Azure CLI installed and logged in, the server will start but every ADO call fails. Each person must install Azure CLI and run az login on the machine running Claude. This applies to both Claude Code and Claude Desktop — Desktop users still install az and run az login in a normal terminal, even though Desktop itself has no terminal.
Prerequisites
Before you start, make sure you have all of the following:
| Requirement | How to check / obtain |
|---|---|
| Node.js ≥ 20 — required to launch the server | The MCP server runs via npx (bundled with Node.js), so both Claude Code and Claude Desktop need Node installed — without it the server never starts. Run node --version; if it's missing or below 20, install a current LTS from nodejs.org. On Windows, install Node on the host (not only inside WSL) if you use Claude Desktop. |
Azure CLI (az) — required for authentication | The MCP server authenticates only through your Azure CLI login, so every machine needs it. Run az --version; install from the Azure CLI docs if missing, then sign in with az login (step 2). |
| Claude Code | You're presumably already using it if you're reading this. |
wasteology ADO org membership — Basic access | You must be a member of the wasteology Azure DevOps organization at the Basic access level. |
The free Stakeholder access level cannot access repos or code. You need at least Basic. If you're not a member — or you're on Stakeholder — ask a Project Collection Administrator (e.g., Kent Gray) to add you or upgrade your access level.
Steps
1. Add the server to your Claude Code MCP config
If you're already working in a repo that has azure-devops configured in its .mcp.json, you can skip to step 2. Otherwise, add this block under mcpServers in your project's .mcp.json:
"azure-devops": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@azure-devops/mcp", "wasteology"]
}
The organization (wasteology) is passed explicitly as the last argument. Because of this, the well-known "az defaults to the stale kgwasteology org" issue does not apply here — the MCP server always targets wasteology.
2. Authenticate with Azure CLI
The MCP server uses your Azure CLI identity — no PAT required. Sign in as yourself:
az login
Sign in with your Wasteology account (you@wasteologygroup.com).
3. Confirm your ADO access
Verify you are a Basic member of the wasteology org with at least Read / Contribute on the repos you need. Repo access can be scoped per-repo, so being an org member doesn't automatically grant access to every repository — if you can't see a repo you expect, that's a per-repo permission, not an org-level one.
4. Restart Claude Code
MCP servers are loaded at startup. Fully restart Claude Code after editing .mcp.json. Once it reloads, the mcp__azure-devops__* tools become available in your session.
5. Verify it works
Ask Claude something that requires the server, for example:
list ADO projects
or
show my work items
Confirm Claude responds using the azure-devops MCP tools (you'll see tool calls prefixed mcp__azure-devops__).
Using Claude Desktop instead
The same server works in Claude Desktop — it just uses a different config file and has a couple of platform gotchas. The ADO access requirement (Basic org member) and the az login auth model are identical.
1. Open the Desktop config
In Claude Desktop: Settings → Developer → Edit Config. This opens (or creates) claude_desktop_config.json:
| OS | Path |
|---|---|
| Windows | %APPDATA%\Claude\claude_desktop_config.json |
2. Add the server
{
"mcpServers": {
"azure-devops": {
"command": "npx",
"args": ["-y", "@azure-devops/mcp", "wasteology"]
}
}
}
Claude Code runs inside your shell and finds npx automatically. Claude Desktop is a Windows GUI app that usually does not load your shell PATH, so npx may not resolve. The fix is to wrap the command in cmd:
{ "command": "cmd", "args": ["/c", "npx", "-y", "@azure-devops/mcp", "wasteology"] }
Node.js ≥ 20 must be installed system-wide (on the Windows host, not only inside WSL).
If you run Claude Code inside WSL, use the standard Linux config from the steps above — plain npx resolves normally in the WSL shell, so you don't need the cmd /c wrapper. The cmd wrapper is only for Claude Desktop, which is a native Windows app.
3. Authenticate (no terminal needed in Desktop)
Desktop has no built-in terminal, but the server reads the Azure CLI credential cache. Just run az login once in a normal terminal on that machine beforehand — Desktop's spawned server picks it up.
4. Fully restart Claude Desktop
Quit completely (from the tray/menu bar — not just closing the window), then reopen. Confirm the azure-devops tools appear via the tools (🔌) icon in the message box.
Unlike Claude Code — where azure-devops can live in a repo's .mcp.json and work the moment you clone that repo — Claude Desktop only has this per-user global config. You edit it by hand; you won't inherit it from a repo.
Troubleshooting
| Symptom | Likely cause / fix |
|---|---|
| Tools don't appear | You didn't restart Claude Code after editing .mcp.json. MCP servers only load at startup — restart fully. |
Server won't start / npx not found | Node.js isn't installed or isn't on PATH. Install Node.js ≥ 20 (nodejs.org). On Claude Desktop (Windows), also wrap the command as cmd /c npx (see the Desktop section) since the GUI app doesn't inherit your shell PATH. |
| 401 / 403 errors | You're not an org member, you're on Stakeholder (needs Basic), or you lack permission on the specific repo. |
| Wrong org / empty results | Ensure the args value is exactly wasteology. A different or missing org value will return nothing or the wrong data. |
az not logged in / az not found | The Azure CLI is required. Install it, then run az login with your Wasteology account. |
"No subscriptions found" after az login | Expected and harmless — the ADO MCP authenticates by identity, not subscription. Re-run az login --allow-no-subscriptions and continue. |
Frequently Asked Questions
Q: Do I need to create a Personal Access Token (PAT)?
No. The server authenticates through your az login session, so there's no PAT to create, rotate, or store.
Q: Which organization does it connect to?
Always wasteology — it's passed explicitly in the config args. This sidesteps the kgwasteology default-org confusion.
Q: I'm a member but still get 403 on a specific repo. Repo access is scoped per-repo. Ask a Project Collection Administrator to grant you Read/Contribute on that specific repository.