phinus-azure-devops-mcp

Model Context Protocol server for Azure DevOps Services (dev.azure.com), focused on work items. Authentication uses a personal access token (PAT) and HTTP Basic auth (empty username, PAT as password), as required by the Azure DevOps REST APIs.

Prerequisites

• Node.js 20+
• An Azure DevOps organization and a PAT with at least:
  • Work Items: Read (for queries and get)
  • Work Items: Read & write (if you use create/update tools)
  • Project and team: Read (for ado_list_projects)

Create a PAT under User settings → Personal access tokens in Azure DevOps.

Configuration

Set these in your MCP host configuration (or copy .env.example for local clone use):

| Variable | Required | Description | |----------|----------|-------------| | AZURE_DEVOPS_ORG | Yes | Organization name only (e.g. contoso), not the full URL. | | AZURE_DEVOPS_PAT | Yes | Personal access token. | | AZURE_DEVOPS_PROJECT | No | Default project when a tool’s project argument is omitted. |

Install and run

The server speaks MCP over stdio and is intended to be launched by an MCP client (for example Cursor), not run interactively in a terminal.

1. From npm (recommended)

Use npx so Cursor downloads and runs the published package:

{
  "mcpServers": {
    "azure-devops": {
      "command": "npx",
      "args": ["-y", "phinus-azure-devops-mcp"],
      "env": {
        "AZURE_DEVOPS_ORG": "your-org",
        "AZURE_DEVOPS_PAT": "your-pat"
      }
    }
  }
}

Or install globally and point Cursor at the binary:

npm install -g phinus-azure-devops-mcp

{
  "mcpServers": {
    "azure-devops": {
      "command": "phinus-azure-devops-mcp",
      "env": {
        "AZURE_DEVOPS_ORG": "your-org",
        "AZURE_DEVOPS_PAT": "your-pat"
      }
    }
  }
}

If your Cursor build supports envFile, you can point it at a file that defines the same variables instead of inlining the PAT.

2. Clone and build

git clone <repo-url>
cd phinus-azure-devops-mcp
npm install
npm run build

Then register the absolute path to the built entry:

{
  "mcpServers": {
    "azure-devops": {
      "command": "node",
      "args": ["/absolute/path/to/phinus-azure-devops-mcp/dist/index.js"],
      "env": {
        "AZURE_DEVOPS_ORG": "your-org",
        "AZURE_DEVOPS_PAT": "your-pat"
      }
    }
  }
}

Local development without rebuilding on every change:

npm run dev

(requires tsx; already a dev dependency.)

Tools

| Tool | Description | |------|-------------| | ado_list_projects | Lists team projects (optional top, skip). | | ado_get_work_item | Gets one work item by id (optional expand). | | ado_query_work_items | Runs WIQL (wiql, optional top, max 200). | | ado_create_work_item | Creates a work item (workItemType, fields map). | | ado_update_work_item | Updates fields by id (fields map, JSON Patch replace). |

Field keys in fields should use reference names such as System.Title and System.Description. Paths are sent to the API as /fields/<ReferenceName>.

Smoke test

1. Set AZURE_DEVOPS_ORG and AZURE_DEVOPS_PAT (and optionally AZURE_DEVOPS_PROJECT).

2. Add the server to Cursor and reload MCP.

3. Call ado_list_projects and confirm you see your projects.

4. Call ado_query_work_items with a small WIQL query scoped to a project you know exists, for example:

   SELECT [System.Id], [System.Title] FROM WorkItems WHERE [System.TeamProject] = @project

   (Pass the project via the tool’s project argument or rely on AZURE_DEVOPS_PROJECT.)

Publish (maintainers)

npm whoami
npm run build
npm pack --dry-run
npm publish --access public

Security notes

• Do not commit .env or embed PATs in the repository.
• The server does not log the PAT; avoid enabling debug logging that prints environment variables.