Azure DevOps MCP Server

A Model Context Protocol (MCP) server implementation for Azure DevOps, allowing AI assistants to interact with Azure DevOps APIs through a standardized protocol.

Overview

This server implements the Model Context Protocol (MCP) for Azure DevOps, enabling AI assistants like Claude to interact with Azure DevOps resources securely. The server acts as a bridge between AI models and Azure DevOps APIs, providing a standardized way to:

• Access and manage projects, work items, repositories, and more
• Create and update work items, branches, and pull requests
• Execute common DevOps workflows through natural language
• Access repository content via standardized resource URIs
• Safely authenticate and interact with Azure DevOps resources

Server Structure

The server is structured around the Model Context Protocol (MCP) for communicating with AI assistants. It provides tools for interacting with Azure DevOps resources including:

• Projects
• Work Items
• Repositories
• Pull Requests
• Branches
• Pipelines

Core Components

• AzureDevOpsServer: Main server class that initializes the MCP server and registers tools
• Feature Modules: Organized by feature area (work-items, projects, repositories, etc.)
• Request Handlers: Each feature module provides request identification and handling functions
• Tool Handlers: Modular functions for each Azure DevOps operation
• Configuration: Environment-based configuration for organization URL, PAT, etc.

The server uses a feature-based architecture where each feature area (like work-items, projects, repositories) is encapsulated in its own module. This makes the codebase more maintainable and easier to extend with new features.

Getting Started

Prerequisites

• Node.js (v16+)
• npm or yarn
• Azure DevOps account with appropriate access
• Authentication credentials (see Authentication Guide for details):
  • Personal Access Token (PAT), or
  • Azure Identity credentials, or
  • Azure CLI login

Running from npm (npx)

If you just want to run the published server package, you do not need to clone or build this repository:

npx -y @fred-shark/mcp-server-azure-devops

Running locally (from source)

From a checkout of this repository:

npm ci
cp .env.example .env   # then edit values
npm run build
npm start              # runs: node dist/index.js

For iterative development (auto-reload):

npm run dev            # runs src/index.ts via ts-node-dev

Command Line Interface (CLI)

In addition to the MCP server, this package includes a command-line interface (azdevops-cli) that provides access to all MCP tools directly from your terminal. The CLI can be used via npx or installed globally:

# Install globally
npm install -g @fred-shark/mcp-server-azure-devops

# Or use with npx (no installation required)
npx -y @fred-shark/mcp-server-azure-devops azdevops-cli --help

Once installed globally, you can use azdevops-cli directly:

azdevops-cli --help
azdevops-cli list-projects

Examples using npx:

# Show help and available commands
npx -y @fred-shark/mcp-server-azure-devops azdevops-cli --help

# List all available tools
npx -y @fred-shark/mcp-server-azure-devops azdevops-cli

# Get user profile information
npx -y @fred-shark/mcp-server-azure-devops azdevops-cli get-me

# List projects with pretty output format
npx -y @fred-shark/mcp-server-azure-devops azdevops-cli list-projects --output pretty

# Get repository tree
npx -y @fred-shark/mcp-server-azure-devops azdevops-cli get-repository-tree --project-id <project-id> --repository-id <repository-id>

# Search for work items
npx -y @fred-shark/mcp-server-azure-devops azdevops-cli search-work-items --query "AssignedTo:me AND State:Active"

# List pull requests with quiet output (JSON only)
npx -y @fred-shark/mcp-server-azure-devops azdevops-cli list-pull-requests --project-id <project-id> --repository-id <repository-id> --quiet

# Collect an evidence pack for a completed work item
azdevops-cli task-context-collect --work-item-id 12345

The CLI uses the same authentication and configuration as the MCP server (via environment variables). Available output formats:

• json: Compact JSON output (default)
• pretty: Formatted JSON with indentation
• Use --quiet flag to suppress additional output and get only data

For a complete list of available commands, run azdevops-cli --help.

Task Context Evidence Pack

task-context-collect is a CLI-only workflow command. It does not call AI APIs and does not generate a final summary.md; it only collects facts and source material for a later analysis step.

Minimal run:

azdevops-cli task-context-collect --work-item-id 12345

Full run:

azdevops-cli task-context-collect \
  --project "MyProject" \
  --work-item-id 12345 \
  --out ".ai-context/tasks/12345" \
  --include-wiki \
  --include-prs \
  --include-commits \
  --include-comments \
  --include-checks \
  --include-raw

When --project is omitted, the command uses the configured default project. When --out is omitted, it writes to .ai-context/tasks/<workItemId>.

The evidence pack contains manifest.json, README.md, normalized work item markdown, raw JSON, extracted links, related PRs, commits, explicitly linked wiki pages, and prompts/summarize-task.prompt.md. Root and direct child work items are scope items. Other linked work items are saved only as context references and are not used for recursive PR/commit/check collection. Wiki pages are downloaded only from explicit links found in scope work items and collected PR/comment text; the collector does not run text search across wiki content.

The collector also prepares compact deterministic files for LLM analysis:

• output/analysis/00-inventory.md and .json
• output/analysis/01-work-items-compact.md and .json
• output/analysis/02-wiki-index.md and .json
• output/analysis/03-pr-index.md and .json
• output/analysis/04-commits-compact.md and .json
• output/analysis/05-analysis-input.md

For Qwen or another model with limited context, pass output/analysis/05-analysis-input.md first. It points to compact follow-up files and explicitly tells the model not to read large raw evidence files into context. Avoid loading manifest.json, links/extracted-links.md, raw JSON, full PR changes.md / comments.md, large wiki pages, or commits/commits.md directly.

Repeated runs overwrite deterministic generated files in output/analysis/, but preserve output/summary.md, output/summary-review.md, and user notes under output/.

Direct child work items are grouped by their dynamic Activity field. Missing activity is written as Unknown. --activity-filter limits full child artifact collection to matching Activity values while still preserving excluded children as context references.

For Azure DevOps Server on-premises, the command uses the existing PAT/config/auth mechanism and records warnings when Services-only or unavailable APIs cannot be read.

Usage with Claude Desktop/Cursor AI

To integrate with Claude Desktop or Cursor AI, add one of the following configurations to your configuration file.

Azure Identity Authentication

Be sure you are logged in to Azure CLI with az login then add the following:

{
  "mcpServers": {
    "azureDevOps": {
      "command": "npx",
      "args": ["-y", "@fred-shark/mcp-server-azure-devops"],
      "env": {
        "AZURE_DEVOPS_ORG_URL": "https://dev.azure.com/your-organization",
        "AZURE_DEVOPS_AUTH_METHOD": "azure-identity",
        "AZURE_DEVOPS_DEFAULT_PROJECT": "your-project-name"
      }
    }
  }
}

Personal Access Token (PAT) Authentication

{
  "mcpServers": {
    "azureDevOps": {
      "command": "npx",
      "args": ["-y", "@fred-shark/mcp-server-azure-devops"],
      "env": {
        "AZURE_DEVOPS_ORG_URL": "https://dev.azure.com/your-organization",
        "AZURE_DEVOPS_AUTH_METHOD": "pat",
        "AZURE_DEVOPS_PAT": "<YOUR_PAT>",
        "AZURE_DEVOPS_DEFAULT_PROJECT": "your-project-name"
      }
    }
  }
}

Azure DevOps Server (on-prem) requires PAT authentication. Example:

{
  "mcpServers": {
    "azureDevOps": {
      "command": "npx",
      "args": ["-y", "@fred-shark/mcp-server-azure-devops"],
      "env": {
        "AZURE_DEVOPS_ORG_URL": "https://server:8080/tfs/DefaultCollection",
        "AZURE_DEVOPS_AUTH_METHOD": "pat",
        "AZURE_DEVOPS_PAT": "<YOUR_PAT>",
        "AZURE_DEVOPS_DEFAULT_PROJECT": "your-project-name"
      }
    }
  }
}

For detailed configuration instructions and more authentication options, see the Authentication Guide.

Authentication Methods

This server supports multiple authentication methods for connecting to Azure DevOps APIs. For detailed setup instructions, configuration examples, and troubleshooting tips, see the Authentication Guide.

Supported Authentication Methods

1. Personal Access Token (PAT) - Simple token-based authentication
2. Azure Identity (DefaultAzureCredential) - Flexible authentication using the Azure Identity SDK
3. Azure CLI - Authentication using your Azure CLI login

Example configuration files for each authentication method are available in the examples directory.

Azure DevOps Server (on-prem) supports PAT authentication only. Azure Identity and Azure CLI are supported for Azure DevOps Services.

Environment Variables

For a complete list of environment variables and their descriptions, see the Authentication Guide.

Key environment variables include:

| Variable | Description | Required | Default | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------- | ---------------------------- | ---------------- | | AZURE_DEVOPS_AUTH_METHOD | Authentication method (pat, azure-identity, or azure-cli) - case-insensitive | No | azure-identity | | AZURE_DEVOPS_ORG_URL | Full URL to your Azure DevOps organization or Server collection (e.g., https://server:8080/tfs/DefaultCollection) | Yes | - | | AZURE_DEVOPS_PAT | Personal Access Token (for PAT auth) | Only with PAT auth | - | | AZURE_DEVOPS_DEFAULT_PROJECT | Default project if none specified | No | - | | AZURE_DEVOPS_API_VERSION | API version to use | No | Latest | | AZURE_TENANT_ID | Azure AD tenant ID (for service principals) | Only with service principals | - | | AZURE_CLIENT_ID | Azure AD application ID (for service principals) | Only with service principals | - | | AZURE_CLIENT_SECRET | Azure AD client secret (for service principals) | Only with service principals | - | | LOG_LEVEL | Logging level (debug, info, warn, error) | No | info |

Troubleshooting Authentication

For detailed troubleshooting information for each authentication method, see the Authentication Guide.

Common issues include:

• Invalid or expired credentials
• Insufficient permissions
• Network connectivity problems
• Configuration errors

Authentication Implementation Details

For technical details about how authentication is implemented in the Azure DevOps MCP server, see the Authentication Guide and the source code in the src/auth directory.

Available Tools

The Azure DevOps MCP server provides a variety of tools for interacting with Azure DevOps resources. For detailed documentation on each tool, please refer to the corresponding documentation.

User Tools

• get_me: Get details of the authenticated user (id, displayName, email) (Azure DevOps Services only)

Organization Tools

• list_organizations: List all accessible organizations (Azure DevOps Services only)

Project Tools

• list_projects: List all projects in an organization
• get_project: Get details of a specific project
• get_project_details: Get comprehensive details of a project including process, work item types, and teams

Repository Tools

• list_repositories: List all repositories in a project
• get_repository: Get details of a specific repository
• get_repository_details: Get detailed information about a repository including statistics and refs
• get_file_content: Get content of a file or directory from a repository
• get_repository_tree: List a repository's file tree from any path and depth
• get_all_repositories_tree: Display hierarchical tree view of files across multiple repositories in a project
• list_commits: List recent commits on a branch including file-level diff content
• create_branch: Create a new branch from an existing one
• create_commit: Commit multiple file changes to a branch using unified diffs or search/replace instructions

Work Item Tools

• get_work_item: Retrieve a work item by ID
• create_work_item: Create a new work item
• update_work_item: Update an existing work item
• list_work_items: List work items in a project
• manage_work_item_link: Add, remove, or update links between work items

Search Tools

• search_code: Search for code across repositories in a project
• search_wiki: Search for content across wiki pages in a project
• search_work_items: Search for work items across projects in Azure DevOps

Pipelines Tools

• list_pipelines: List pipelines in a project
• get_pipeline: Get details of a specific pipeline
• list_pipeline_runs: List recent runs for a pipeline with optional filters
• get_pipeline_run: Get detailed run information and artifact summaries
• download_pipeline_artifact: Download a single artifact file as text
• pipeline_timeline: Retrieve the stage and job timeline for a run
• get_pipeline_log: Retrieve raw or JSON-formatted log content
• trigger_pipeline: Trigger a pipeline run with customizable parameters

Wiki Tools

• get_wikis: List all wikis in a project
• get_wiki_page: Get content of a specific wiki page as plain text

Pull Request Tools

• create_pull_request - Create a new pull request
• get_pull_request - Get a pull request by ID
• list_pull_requests - List pull requests in a repository
• add_pull_request_comment - Add a comment to a pull request
• get_pull_request_comments - Get comments from a pull request
• update_pull_request - Update an existing pull request (title, description, status, draft state, reviewers, work items)
• get_pull_request_changes - List changes in a pull request and policy evaluation status
• get_pull_request_checks - Summarize status checks, policy evaluations, and their related pipelines

For comprehensive documentation on all tools, see the Tools Documentation.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for contribution guidelines.

Star History

License

MIT