Azure DevOps MCP Server for Cursor

A Model Context Protocol (MCP) server that exposes Azure DevOps (Builds, Pipelines, and Boards/Work Items) as callable tools so you can drive DevOps tasks from Cursor chat.

Features

• Tools you can call from Cursor: list projects, list pipelines/builds, run WIQL queries, get/create/update work items, add comments, list sprints/iterations, list board columns, and list sprint backlog items

• Secure auth via Azure DevOps Personal Access Token (PAT) using environment variables (no tokens in code)

• Built with TypeScript for type safety and extensibility

Related MCP server: azure-devops-mcp

Architecture

• MCP server runs locally; Cursor launches it and calls "tools"

• The server makes REST calls to Azure DevOps with your PAT

Prerequisites

• Node.js 20+ (node -v)

• Cursor installed

• Access to an Azure DevOps organization and project

Setup

Automated Setup (Recommended)

1. Create a Personal Access Token (PAT) in Azure DevOps:

• Go to User Settings → Personal access tokens → New Token

• Required permissions: Work Items: Read & Write, Build: Read, Project and Team: Read

2. Run the setup script:

macOS/Linux:

Windows PowerShell:

3. Follow the prompts to enter:

• Azure DevOps Organization (e.g., "mycompany")

• Azure DevOps Project (optional)

• Personal Access Token

4. Restart Cursor completely and test with: "List my Azure DevOps projects"

The setup script will automatically:

• Build the TypeScript project

• Find your Node.js installation

• Create/update your Cursor MCP configuration (~/.cursor/mcp.json)

• Back up any existing configurations

Manual Setup

If the automated setup doesn't work, you can configure manually:

Step 1: Create a Personal Access Token (PAT)

1. In Azure DevOps, go to User Settings → Personal access tokens → New Token

2. Choose a short Expiration (e.g., 30–90 days)

3. Scopes (start minimal; add more only when needed):

   • Build: Read (for pipelines/builds)

   • Work Items / Work: Read; add Read & Write if you want to create/update items, change states, add comments, or move to sprints

   • (Optional) Code: Read (if you'll surface PRs/commits later)

4. Copy the token and store it securely

Step 2: Install Dependencies

The project is already set up with all required dependencies. If you need to reinstall:

Step 3: Environment Variables

Set up your environment variables. You can either:

Option A: Export in your shell

Option B: Create a (add to .gitignore)

Step 4: Test the Server

Test that the server runs without errors:

Step 5: Register with Cursor

Create or edit ~/.cursor/mcp.json:

Then set CURSOR_SECRET_ADO_PAT as an environment variable or Cursor secret.

Available Tools

Organization/Project Tools

• list_projects - List all projects in the Azure DevOps organization

Pipeline/Build Tools

• list_pipelines - List all pipelines in the project

• list_builds - List builds with optional filters (definitions, branch, top N, pagination)

Work Item Tools

• wiql_query_team - Run WIQL queries against a team

• work_item_get - Get a single work item by ID

• work_items_get - Get multiple work items by IDs with optional field filtering

• work_item_create - Create a new work item

• work_item_update - Update an existing work item

• work_item_comment_add - Add a comment to a work item

Board/Sprint Tools

• boards_list_columns - List board columns for a team

• iterations_list - List team iterations/sprints (past, current, future)

• iteration_work_items - Get work items in a specific iteration

• board_move - Move a work item to a different state/sprint

Usage Examples

List Projects

List Pipelines

Get Latest Builds

Find Work Items in Current Sprint

1. Get current sprint:

   iterations_list { "team": "MyTeam", "timeframe": "current" }

2. Get work items in sprint:

   iteration_work_items { "team": "MyTeam", "iterationId": "<sprint-guid>" }

Query Work Items with WIQL

Move Work Item to Sprint and Start Work

Create a Bug

Troubleshooting

Setup Issues

• "Node.js not found": Install Node.js from nodejs.org

• "Permission denied" (macOS/Linux): Run chmod +x setup-mcp.sh

• "Execution policy" error (Windows): Run Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

• "No tools found" in Cursor: Restart Cursor completely and check MCP config file was created

Runtime Issues

• 401/403 errors: Token wrong, expired, or missing required scopes

• 404 errors: Wrong org/project/team name or insufficient access

• Board column changes don't work: Set System.State mapped to that column (not the column field itself)

• Current sprint empty: Team's iteration path may differ from project default—check team name and iteration settings

Manual Configuration

If automated setup fails, manually edit your MCP config file:

Location: ~/.cursor/mcp.json (macOS/Linux) or %USERPROFILE%\.cursor\mcp.json (Windows)

Common Field Names

• System.Title

• System.State (controls board column via mapping)

• System.IterationPath (sprint)

• System.AreaPath

• System.Description

• Microsoft.VSTS.Scheduling.StoryPoints

• Microsoft.VSTS.Common.Priority

Development

Build

Development Mode

Security

• Keep PATs scoped to minimum required permissions

• Use short-lived tokens (30-90 days)

• Never commit tokens to code

• Use environment variables or secure secrets management

License

MIT