Cursor Azure DevOps MCP Server

A Model Context Protocol (MCP) server for integrating Azure DevOps with Cursor IDE. This tool allows Claude AI in Cursor to interact with Azure DevOps, providing access to projects, work items, repositories, and pull requests.

Features

• Get Azure DevOps projects
• Retrieve work items by ID
• Fetch multiple work items
• List repositories in a project
• Get pull requests for a repository
• View pull request details and threads
• Retrieve work item attachments (images, PDFs, and other files)
• Get work item comments with metadata (including mentions and reactions)
• Get detailed code changes for pull requests (view file contents before and after changes)
• Create comments on pull requests (with support for replying to existing comments)
• Test Plan Management:
  • List all test plans in a project
  • Get test plan details by ID
  • List test suites in a test plan
  • Get test suite details by ID
  • List test cases in a test suite
• Smart Response Handling:
  • Automatic truncation of large responses to fit AI model limits
  • Preservation of essential fields in truncated responses
  • Metadata about truncation status and original size
• Project Configuration:
  • Default project support from configuration
  • Fallback to configuration when project is not specified
  • Proper error handling for missing project information

Changelog

Version 1.0.3

Added

• Test Plan Management Support:
  • New tool: azure_devops_test_plans - List all test plans for a project
  • New tool: azure_devops_test_plan - Get a test plan by ID
  • New tool: azure_devops_test_suites - List all test suites for a test plan
  • New tool: azure_devops_test_suite - Get a test suite by ID
  • New tool: azure_devops_test_cases - List all test cases for a test suite

Enhanced

• Response Size Management:
  • Added intelligent response truncation (max 50KB by default)
  • Preserved essential fields in truncated responses
  • Added truncation metadata in responses
• Project Configuration:
  • Added support for default project from configuration
  • Improved project parameter handling in all test-related methods
  • Added proper error handling for missing project information

Fixed

• Parameter ordering in test suite methods to comply with TypeScript requirements
• Error handling improvements in test-related API calls
• Response formatting for large test suite responses

Installation

Global Installation

npm install -g cursor-azure-devops-mcp

Local Installation

npm install cursor-azure-devops-mcp

Configuration

The server can be configured using multiple sources, with the following priority:

1. Command line arguments
2. VSCode/Cursor IDE settings
3. Environment variables / .env file
4. Default values

Command Line Arguments

You can configure the server using command line arguments:

npx cursor-azure-devops-mcp --azure-org-url=https://dev.azure.com/your-organization --azure-token=your-token --azure-project=YourProject

Available options:

Option	Alias	Description
--azure-org-url	--org	Azure DevOps organization URL
--azure-token	--token	Azure DevOps personal access token
--azure-project	--project	Default Azure DevOps project name
--port	-p	Server port (for HTTP mode)
--host	-h	Server hostname (for HTTP mode)
--log-level	--log	Logging level (error, warn, info, debug)
--help	-?	Show help

VSCode/Cursor IDE Settings

You can configure the server in your VSCode or Cursor IDE settings:

1. Global settings: ~/.vscode/settings.json or ~/.cursor/settings.json
2. Workspace settings: .vscode/settings.json or .cursor/settings.json

Example settings:

{
  "azureDevOps.organization": "your-organization",
  "azureDevOps.token": "your-personal-access-token",
  "azureDevOps.project": "YourProject",
  "cursor-azure-devops-mcp": {
    "port": 3000,
    "logLevel": "info"
  }
}

Environment Variables

Create a .env file in your project root with the following variables:

AZURE_DEVOPS_ORG_URL=https://dev.azure.com/your-organization
AZURE_DEVOPS_TOKEN=your-personal-access-token
AZURE_DEVOPS_PROJECT=YourProject
PORT=3000
LOG_LEVEL=info

You can also copy the provided .env.example file:

cp .env.example .env

Then edit the file with your Azure DevOps credentials.

Usage

Running with npx

The easiest way to use this MCP server is with npx:

npx cursor-azure-devops-mcp

Setting up in Cursor IDE (Version 0.46.9+)

Cursor IDE supports two methods for connecting to MCP servers: Command mode and SSE mode.

Option 1: Command Mode (Recommended)

The Command mode runs the MCP server as a process directly from Cursor. This is the most reliable method and should be your first choice:

1. Open Cursor IDE

2. Go to Settings > Features > MCP Servers

3. Click "Add New MCP Server"

4. Enter a name for your server (e.g., "Azure DevOps")

5. Select "command" from the dropdown

6. Enter the command to run the server:

   cursor-azure-devops-mcp
   

   If you haven't installed it globally, you can use npx:

   npx cursor-azure-devops-mcp
   

7. Click "Add"

Important: When using Command mode, the server will automatically use your environment variables from your system or from a .env file in your current working directory. Make sure your .env file is properly set up with your Azure DevOps credentials.

Troubleshooting Command Mode:

If you encounter the error "server.setRequestHandler is not a function" or similar errors:

1. Make sure you have the latest version of the package installed
2. Try reinstalling the package: npm install -g cursor-azure-devops-mcp
3. Check that your .env file is correctly set up with your Azure DevOps credentials

Option 2: SSE Mode (Alternative)

Note: SSE mode is more prone to connection issues. If you're experiencing problems, please use Command mode instead.

The SSE mode connects to an HTTP server with Server-Sent Events:

1. First, start the HTTP server with SSE support:

   npm run sse-server
   

   or

   npx cursor-azure-devops-mcp-sse
   

   This will start a server on port 3000 by default.

2. Open Cursor IDE

3. Go to Settings > Features > MCP Servers

4. Click "Add New MCP Server"

5. Enter a name for your server (e.g., "Azure DevOps SSE")

6. Select "sse" from the dropdown

7. Enter the SSE endpoint URL:

   http://localhost:3000/sse
   

8. Click "Add"

Windows Users

If you're using Windows and experiencing issues with the command mode, try this format:

cmd /k npx cursor-azure-devops-mcp

mcp.json installation

{
    "azure-devops": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "cursor-azure-devops-mcp",
        "--azure-org-url",
        "https://your-organization.visualstudio.com",
        "--azure-token",
        "your-personal-access-token",
        "--azure-project",
        "your-project"
      ]
    }
}

Using in Your Code

const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');
const { registerTools } = require('cursor-azure-devops-mcp');
const azureDevOpsService = require('cursor-azure-devops-mcp/lib/azure-devops-service');

// Create MCP server
const server = new McpServer({
  name: 'cursor-azure-devops-mcp',
  version: '1.0.0'
});

// Register Azure DevOps tools with the server
registerTools(server, azureDevOpsService);

// Connect to your transport of choice
// ...

Available Tools

Tool Name	Description	Required Parameters
azure_devops_projects	Get all projects	None
azure_devops_work_item	Get a specific work item	id (number)
azure_devops_work_items	Get multiple work items	ids (array of numbers)
azure_devops_repositories	Get repositories for a project	project (string)
azure_devops_pull_requests	Get pull requests from a repository	repositoryId (string), project (string)
azure_devops_pull_request_by_id	Get a specific pull request	repositoryId (string), pullRequestId (number), project (string)
azure_devops_pull_request_threads	Get threads from a pull request	repositoryId (string), pullRequestId (number), project (string)
azure_devops_work_item_attachments	Get attachments for a work item	id (number)
azure_devops_work_item_comments	Get comments for a work item	id (number)
azure_devops_pull_request_changes	Get detailed PR code changes	repositoryId (string), pullRequestId (number), project (string)
azure_devops_pull_request_file_content	Get content of a specific file in a pull request	repositoryId (string), pullRequestId (number), filePath (string), objectId (string), project (string), optional: returnPlainText (boolean), startPosition (number), length (number)
azure_devops_branch_file_content	Get file content directly from a branch	repositoryId (string), branchName (string), filePath (string), project (string), optional: returnPlainText (boolean), startPosition (number), length (number)
azure_devops_create_pr_comment	Create a comment on a pull request	repositoryId (string), pullRequestId (number), project (string), content (string), and other optional parameters
azure_devops_test_plans	List all test plans for a project	project (string)
azure_devops_test_plan	Get a test plan by ID	project (string), testPlanId (number)
azure_devops_test_suites	List all test suites for a test plan	project (string), testPlanId (number)
azure_devops_test_suite	Get a test suite by ID	project (string), testPlanId (number), testSuiteId (number)
azure_devops_test_cases	List all test cases for a test suite	project (string), testPlanId (number), testSuiteId (number)

Test Management Tools

The test management tools provide comprehensive access to Azure DevOps test plans, suites, and cases:

• Automatic Project Handling: All test tools support using the default project from configuration
• Smart Response Truncation: Large responses are automatically truncated to fit AI model limits while preserving essential information
• Metadata Preservation: Even in truncated responses, important metadata like IDs, names, and relationships are preserved
• Error Handling: Comprehensive error handling with detailed error messages

Example Usage:

List all test plans in a project:

{
  "project": "YourProject"
}

Get a specific test suite:

{
  "project": "YourProject",
  "testPlanId": 185735,
  "testSuiteId": 186771
}

List test cases in a suite:

{
  "project": "YourProject",
  "testPlanId": 185735,
  "testSuiteId": 186771
}

When working with test management tools, you should:

1. First retrieve the test plans for your project using azure_devops_test_plans
2. Use a specific test plan ID to get test suites with azure_devops_test_suites
3. Finally, get test cases for a specific suite using azure_devops_test_cases

The response format includes truncation metadata when necessary:

{
  "items": [...],
  "totalCount": 100,
  "isTruncated": true,
  "truncatedCount": 80,
  "message": "Response was truncated. Showing 20 of 100 items."
}