arcade-azure-devops-mcp

An MCP server for Azure DevOps built with Arcade.dev. Enables AI assistants to interact with Azure DevOps projects, work items, repositories, pipelines, wikis, and more.

Features

21 tools covering:

Core: List projects, teams, search identities
Work Items: Get, create, update, query work items; add comments
Repositories: List repos, branches, pull requests; create PRs
Pipelines: List definitions, builds; queue builds; run pipelines
Wikis: List wikis, get wiki pages
Search: Search code across repositories

Quick Start

1. Install dependencies

uv sync

2. Configure credentials

You have two options for providing Azure DevOps credentials:

Option A: Environment Variables (`.env` file)

Copy the example environment file and add your credentials:

cp .env.example .env

Edit .env:

AZURE_DEVOPS_ORG=your-organization-name
AZURE_DEVOPS_PAT=your-personal-access-token

Option B: Arcade Secrets (recommended for production)

If no .env file or environment variables are found, the server automatically falls back to Arcade Secrets. This is ideal for:

Publishing to the Arcade marketplace
Sharing the toolkit without exposing credentials
Production deployments via Arcade Deploy

Configure secrets in Arcade:

# Login to Arcade
arcade login

# Set your secrets
arcade secrets set AZURE_DEVOPS_ORG "your-organization-name"
arcade secrets set AZURE_DEVOPS_PAT "your-personal-access-token"

Or configure via the Arcade Dashboard.

How it works:

Server checks for environment variables first
If not found, requests secrets from Arcade Cloud via context.get_secret()
Arcade prompts user to authorize secret access (first time only)

3. Create a Personal Access Token (PAT)

Go to https://dev.azure.com/{your-org}/_usersSettings/tokens
Click "New Token"
Select scopes: Code (Read/Write), Work Items (Read/Write), Build (Read/Execute), Wiki (Read/Write)
Copy the token

4. Run the MCP Server

# stdio transport (default) - for Claude Desktop, CLI tools
uv run server.py stdio

# http transport - for Cursor, VS Code
uv run server.py http

For HTTP transport, view the API docs at http://127.0.0.1:8000/docs

Configure MCP Clients

Cursor IDE

arcade configure cursor

Or manually add to .cursor/mcp.json:

With environment variables:

{
  "mcpServers": {
    "azure-devops": {
      "command": "uv",
      "args": ["run", "server.py", "stdio"],
      "cwd": "/path/to/arcade-azure-devops-mcp",
      "env": {
        "AZURE_DEVOPS_ORG": "your-org",
        "AZURE_DEVOPS_PAT": "your-pat"
      }
    }
  }
}

With Arcade Secrets (no local credentials):

{
  "mcpServers": {
    "azure-devops": {
      "command": "uv",
      "args": ["run", "server.py", "stdio"],
      "cwd": "/path/to/arcade-azure-devops-mcp"
    }
  }
}

VS Code

arcade configure vscode

Claude Desktop

arcade configure claude

Available Tools

Category	Tool	Description
Core	`list_projects`	List all projects in the organization
	`get_project`	Get project details
	`list_teams`	List teams in a project
	`search_identities`	Search for users/groups
Work Items	`get_work_item`	Get a work item by ID
	`create_work_item`	Create a new work item
	`update_work_item`	Update an existing work item
	`run_work_item_query`	Run a WIQL query
	`my_work_items`	Get work items assigned to you
	`add_work_item_comment`	Add a comment to a work item
Repos	`list_repositories`	List Git repositories
	`list_branches`	List branches in a repository
	`list_pull_requests`	List pull requests
	`create_pull_request`	Create a new PR
Pipelines	`list_build_definitions`	List pipeline definitions
	`list_builds`	List builds
	`queue_build`	Queue a new build
	`run_pipeline`	Start a pipeline run
Wikis	`list_wikis`	List wikis
	`get_wiki_page`	Get wiki page content
Search	`search_code`	Search code across repositories

Architecture

Request Flow

┌────────────┐      ┌────────────┐      ┌──────────────┐      ┌─────────────┐
│ MCP Client │      │ MCP Server │      │ Arcade Cloud │      │ Azure DevOps│
└─────┬──────┘      └─────┬──────┘      └──────┬───────┘      └──────┬──────┘
      │                   │                    │                     │
      │  Call tool        │                    │                     │
      │──────────────────>│                    │                     │
      │                   │                    │                     │
      │                   │ Check env vars     │                     │
      │                   │◄──────────────────►│                     │
      │                   │                    │                     │
      │                   │ [If env vars missing - paid tier]        │
      │                   │ get_secret()       │                     │
      │                   │───────────────────>│                     │
      │                   │<───────────────────│                     │
      │                   │                    │                     │
      │                   │ API Request (Basic Auth)                 │
      │                   │─────────────────────────────────────────>│
      │                   │<─────────────────────────────────────────│
      │                   │                    │                     │
      │  Tool result      │                    │                     │
      │<──────────────────│                    │                     │
      │                   │                    │                     │

sequenceDiagram
    participant C as MCP Client
    participant S as MCP Server
    participant A as Arcade Cloud
    participant D as Azure DevOps

    C->>S: Call tool (e.g., list_projects)
    
    Note over S: Resolve Credentials
    S->>S: Check env: AZURE_DEVOPS_ORG
    S->>S: Check env: AZURE_DEVOPS_PAT
    
    alt Environment variables exist
        S->>S: Use local credentials
    else Environment variables missing (paid tier)
        S->>A: context.get_secret("AZURE_DEVOPS_ORG")
        A-->>S: Return organization name
        S->>A: context.get_secret("AZURE_DEVOPS_PAT")
        A-->>S: Return PAT token
    end
    
    Note over S,D: API Request
    S->>D: GET /{org}/_apis/projects?api-version=7.1
    D-->>S: JSON response
    
    S-->>C: Tool result

Component Overview

┌─────────────────────────────────────────────────────────────────────────────┐
│                              MCP CLIENT                                     │
│                         (Cursor / Claude Desktop)                           │
└─────────────────────────────────┬───────────────────────────────────────────┘
                                  │ MCP Protocol (stdio/http)
                                  ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                              MCP SERVER                                     │
│  ┌─────────────────┐  ┌──────────────────┐  ┌─────────────────────────┐    │
│  │  MCPApp         │  │  Azure DevOps    │  │  AuthManager            │    │
│  │  Framework      │──│  Tools (21)      │──│  (credential resolver)  │    │
│  └─────────────────┘  └──────────────────┘  └───────────┬─────────────┘    │
└─────────────────────────────────────────────────────────┼───────────────────┘
                                                          │
                        ┌─────────────────────────────────┼─────────────────┐
                        │                                 │                 │
                        ▼ [Priority 1]                    ▼ [Priority 2]    │
          ┌─────────────────────────┐       ┌───────────────────────┐       │
          │  Local .env /           │       │  Arcade Cloud         │       │
          │  Environment Variables  │       │  (Secrets API)        │       │
          └─────────────────────────┘       │  [Paid tier only]     │       │
                                            └───────────────────────┘       │
                                                                            │
                                                          ┌─────────────────┘
                                                          ▼
                                            ┌───────────────────────┐
                                            │  Azure DevOps         │
                                            │  REST API v7.1        │
                                            └───────────────────────┘

flowchart TB
    subgraph MCPClient [MCP Client]
        Cursor[Cursor / Claude Desktop]
    end
    
    subgraph MCPServer [MCP Server]
        App[MCPApp Framework]
        Tools[Azure DevOps Tools]
        Auth[AuthManager]
    end
    
    subgraph External [External Services]
        Arcade[Arcade Cloud - Secrets API]
        ADO[Azure DevOps REST API v7.1]
    end
    
    subgraph Local [Local Config]
        Env[.env file / Environment Variables]
    end
    
    Cursor -->|MCP Protocol| App
    App --> Tools
    Tools --> Auth
    Auth -->|Priority 1| Env
    Auth -.->|Priority 2 - Paid Tier| Arcade
    Auth -->|Basic Auth| ADO

Credential Resolution Priority

Environment variables (.env file or system env) - checked first
Arcade Cloud secrets - fallback if env vars not found (requires paid Arcade tier)

Project Structure

arcade-azure-devops-mcp/
├── server.py                  # MCP server entry point with all tools
├── arcade_azure_devops_mcp/   # Azure DevOps client library
│   ├── __init__.py
│   ├── client.py              # REST API client (httpx)
│   ├── models.py              # Pydantic models
│   └── auth/                  # Authentication
│       ├── __init__.py
│       ├── manager.py         # Credential management (env + Arcade secrets)
│       └── oauth.py           # OAuth/Azure AD (optional)
├── pyproject.toml             # Dependencies & entry points
├── .env.example               # Environment template
└── README.md

Development

# Install with dev dependencies
uv sync --all-extras

# Run tests
uv run pytest

Publishing to Arcade

To publish this toolkit to the Arcade marketplace:

# Ensure pyproject.toml has correct entry points
arcade publish

Users can then install via:

arcade install arcade-azure-devops-mcp

License

MIT