Azure DevOps MCP Server

Latest Release: v1.1.3

Language selector: English | Italiano

English Version

Author: Varnier Gatto (mcp_dev@jitime.com)

This is a Model Context Protocol (MCP) server that enables AI assistants (such as Claude Desktop, Antigravity, etc.) to interact directly with Azure DevOps.

It provides a rich suite of tools to manage Work Items (Bugs, User Stories, Tasks), interact with Git repositories (read files, commit/push, manage Pull Requests), trigger and monitor Pipelines, and search for users or groups within the organization.

Key Features

• Credential Security: Credentials (Username and PAT) are stored locally in encrypted form (.azure-devops-config.enc in the working directory) using the AES-256-GCM encryption algorithm. The key is safely generated and stored in your user profile folder (~/.antigravity-devops-key).

• Multi-Organization and Multi-Project Support: Seamlessly configure and interact with multiple Azure DevOps projects and organizations.

• Offline API Database: Includes a local cache (api-directory.json) of Microsoft Azure DevOps API specs to allow fast, offline endpoint searches.

• Flexible REST Client: Includes a generic tool (api_call) capable of executing any HTTP request (GET, POST, PATCH, etc.) against the Azure DevOps REST APIs.

• Remote HTTP Mode: Optionally serves the same tools over Streamable HTTP (/mcp) and legacy SSE (/sse), with bearer-token or Microsoft Entra ID authentication and per-session credentials. See Remote Mode (HTTP).

Exposed Tools

Configuration & Connection

• connection_configure: Save credentials (URL, Username, PAT) for a specific organization/project.

• connection_test: Verify connection and PAT validity for the default organization.

Generic REST Client & API Directory

• api_call: Execute arbitrary HTTP REST requests (GET, POST, PATCH, DELETE, etc.) against Azure DevOps.

• api_docs: Search the offline API directory for matching endpoints or schemas.

• api_info: Retrieve details of a specific endpoint schema, including required parameters.

Work Item Tracking (WIT)

• workitem_get: Retrieve details of a work item by ID.

• workitem_create: Create a new work item (Bug, Task, User Story).

• workitem_update: Update fields of an existing work item.

• workitem_query: Run complex searches using the WIQL (Work Item Query Language) format (automatically scoped to @project when a project is configured, with detail retrieval chunked in batches of 200 items).

• workitem_comment: Add discussion comments to a work item.

• workitem_link: Link two work items (e.g., Parent/Child, Related, Duplicate).

Git Integration

• git_repos: List Git repositories within the configured project.

• git_file: Read file contents from a specific repository and branch (default: main).

• git_push: Commit and push file modifications, additions, or deletions directly to a remote branch.

• git_pr_create: Create a new Pull Request.

• git_pr_get: Retrieve Pull Request status and details.

• git_pr_update: Update Pull Request status (e.g., to completed, abandoned, active).

• git_pr_comment_create: Create review comments on specific files and lines inside a PR.

• git_pr_comment_list: Retrieve all comment threads for a PR.

Pipeline Management

• pipeline_run: Trigger a pipeline run with optional parameters.

• pipeline_get: Retrieve status of a pipeline run.

• pipeline_logs: Fetch combined log text for a pipeline run.

Identity Search

• identity_search: Search for users or groups in the organization by name or email.

Prerequisites

• Node.js (version 18 or higher)

• npm (included with Node.js)

Installing via Smithery

To install Azure DevOps MCP Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install github-y8ge/mcp-azure-devops --client claude

Manual Installation

1. Install Node.js 18 or newer (includes npm).

2. Clone the repository and install the dependencies:

   git clone https://github.com/varnierg/MCP-for-AZURE-Devops.git
   cd MCP-for-AZURE-Devops
   npm install

3. The compiled server (dist/index.js) is already included. Rebuild it only if you change the TypeScript sources:

   npm run build

Configuration

The server needs your Azure DevOps organization (or a project/dashboard URL), your e-mail/username and an Azure DevOps Personal Access Token (PAT).

Generate a PAT in Azure DevOps

1. Open your Azure DevOps portal.

2. Click on the user settings icon in the top right, and select Personal Access Tokens.

3. Click New Token.

4. Select the necessary scopes. To use all MCP tools, we recommend:

   • Code: Read & Write (required for Git pushes, PRs, and reading files)

   • Work Items: Read & Write (required for managing tasks, stories, and bugs)

   • Build: Read & Execute (if you want to trigger and view pipeline runs)

   • Graph: Read (required for searching identities/users)

5. Copy the generated token (it won't be shown again).

How to provide the credentials (choose one)

• At runtime (default): the AI agent calls connection_configure with URL, username and PAT the first time it connects to an organization. Credentials are encrypted and saved locally.

• Setup wizard: run npm run setup and enter the project URL, username and PAT. The wizard tests the connection before saving.

• Startup arguments / environment variables: --org, --username, --pat, --project, or AZURE_DEVOPS_ORG, AZURE_DEVOPS_USERNAME, AZURE_DEVOPS_PAT, AZURE_DEVOPS_PROJECT.

Running & Usage

Integrate with AI Clients (stdio)

Add the server to your client's MCP configuration. Example for Claude Desktop (%APPDATA%\Claude\claude_desktop_config.json on Windows, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "mcp-azure-devops": {
      "command": "node",
      "args": [
        "C:\\Path\\To\\MCP-for-AZURE-Devops\\dist\\index.js"
      ]
    }
  }
}

Note: replace the path with the absolute path of the cloned repository (on macOS/Linux e.g. /Users/<you>/MCP-for-AZURE-Devops/dist/index.js). The same command + args block works in other stdio clients (Antigravity, Cursor, VS Code, …).

Remote Mode (HTTP)

The server can also expose its tools over HTTP, so that one instance can be shared by several clients or run in a container. Full guide: Remote HTTP Mode (wiki).

Start: node dist/index.js --port 8080 (or PORT / MCP_PORT; Linux/macOS and containers default to 8080). The stdio transport stays active too.

Listen address: 127.0.0.1 by default (local clients only). To accept connections from other machines use --host 0.0.0.0 or MCP_HOST=0.0.0.0 (the Docker image already sets it), and enable authentication.

Authentication of the MCP endpoint (combinable):

Without any of them the server runs in open mode (only for localhost/testing). More than 5 failed authentication attempts (with an invalid Authorization header) from an IP within 10 minutes lock that IP out for 30 minutes; unauthenticated OAuth discovery probes return 401 WWW-Authenticate without counting toward the lockout. An Entra ID token issued for Azure DevOps is also used to call Azure DevOps on behalf of the user, so no PAT is needed.

Azure DevOps credentials:

• Per session / per authenticated user (multi-user): headers X-Azure-DevOps-Org, X-Azure-DevOps-PAT, X-Azure-DevOps-Username, X-Azure-DevOps-Project (recommended), or query parameters organization, pat, … / config=<base64 JSON> (Smithery format). connection_configure keeps credentials in memory only (never on disk); when signed in via Microsoft OAuth, only url is required (omit token to use your OAuth session, or pass a custom PAT to connect as a different DevOps user). For authenticated requests (Microsoft Entra ID UPN or Bearer token), in-memory credentials also persist per authenticated user (12-hour TTL) so stateless HTTP MCP clients that open a new session per tool call retain their configured organization/project. Idle Mcp-Session-Id transports are dropped after 30 minutes.

• Server-wide (single user): AZURE_DEVOPS_ORG, AZURE_DEVOPS_PAT, AZURE_DEVOPS_USERNAME, AZURE_DEVOPS_PROJECT. In this case authentication is mandatory.

Docker (local):

docker build -t mcp-azure-devops .
docker run -p 8080:8080 -e MCP_AUTH_TOKEN=a-long-random-secret mcp-azure-devops
# Client endpoint: http://localhost:8080/mcp

Client configuration (clients with remote support; the key may be url or serverUrl depending on the client):

{
  "mcpServers": {
    "azure-devops": {
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer a-long-random-secret",
        "X-Azure-DevOps-Org": "my-org",
        "X-Azure-DevOps-PAT": "<your-pat>"
      }
    }
  }
}

For stdio-only clients use the bridge: npx -y mcp-remote http://localhost:8080/mcp --header "Authorization: Bearer a-long-random-secret".

Verification

Run the integrated test suite to verify internal helper functions (URL parser, crypto, config store, offline API database):

npm run test

Setting up a Test Environment / Creating Test Data

To test the Azure DevOps MCP tools (Work Items, Git, Pipelines, and Identities), you can set up a dedicated sandbox environment:

1. Create a Test Organization: Go to dev.azure.com and create a free personal organization (e.g., my-sandbox-org).

2. Create a Test Project: Within your organization, create a new private project (e.g., TestProject).

3. Populate Test Data:

   • Git Repository: Initialize the default repository with a main branch and add a few sample files (e.g., README.md, index.html) to test the Git tools.

   • Work Items: Create a couple of sample Work Items (e.g., a Bug with title "Test Bug" and a Task with title "Test Task") to test WIT tools.

   • Pipelines: Create a basic pipeline (e.g., using a simple starter YAML template) to test pipeline runs and log retrieval.

   • Identities: Add at least one other user or group in your project settings to test identity search.

Related MCP server: Azure DevOps MCP Server

Versione Italiana

Autore: Varnier Gatto (mcp_dev@jitime.com)

Questo è un server Model Context Protocol (MCP) che consente ai modelli di intelligenza artificiale (come Claude Desktop, Antigravity, ecc.) di interagire direttamente con Azure DevOps.

Il server fornisce una ricca suite di strumenti per gestire Work Item (Bug, User Story, Task), interagire con i repository Git (leggere file, effettuare commit/push, gestire Pull Request), monitorare pipeline ed eseguire ricerche di identità all'interno dell'organizzazione.

Caratteristiche Principali

• Sicurezza delle Credenziali: Le credenziali (Username e PAT) vengono salvate localmente in formato cifrato (.azure-devops-config.enc nella directory di lavoro) tramite algoritmo AES-256-GCM. La chiave di cifratura viene generata in modo sicuro e memorizzata nella cartella utente (~/.antigravity-devops-key).

• Supporto Multi-Organization e Multi-Project: È possibile configurare e gestire molteplici progetti e organizzazioni DevOps.

• Cache API Offline: Include un database locale (api-directory.json) contenente la documentazione delle API Microsoft Azure DevOps per permettere ricerche rapide offline degli endpoint.

• Client REST flessibile: Oltre ai comandi specifici, espone uno strumento generico (api_call) in grado di eseguire qualsiasi richiesta HTTP (GET, POST, PATCH, ecc.) verso le API REST di Azure DevOps.

• Modalità Remota HTTP: Opzionalmente espone gli stessi strumenti via Streamable HTTP (/mcp) e SSE legacy (/sse), con autenticazione tramite bearer token o Microsoft Entra ID e credenziali per singola sessione. Vedi Modalità Remota (HTTP).

Elenco degli Strumenti (Tools) Esposti

Configurazione e Connessione

• connection_configure: Configura le credenziali (URL, Username, PAT) per un'organizzazione o progetto.

• connection_test: Verifica la connessione e la validità del PAT per l'organizzazione configurata di default.

Client REST Generico & Elenco API (Directory)

• api_call: Esegue qualsiasi richiesta REST HTTP (GET, POST, PATCH, DELETE, ecc.) verso Azure DevOps.

• api_docs: Cerca all'interno dell'elenco API locale per trovare endpoint o schemi corrispondenti.

• api_info: Recupera i dettagli sullo schema di uno specifico endpoint, inclusi i parametri richiesti.

Gestione Work Items (WIT)

• workitem_get: Recupera i dettagli di un determinato work item tramite ID.

• workitem_create: Crea un nuovo work item (Bug, Task, User Story).

• workitem_update: Aggiorna i campi di un work item esistente.

• workitem_query: Esegue ricerche complesse tramite il linguaggio di query WIQL (Work Item Query Language), filtrando automaticamente per il progetto configurato (@project) e recuperando i dettagli in blocchi da 200 elementi.

• workitem_comment: Aggiunge commenti all'area di discussione di un work item.

• workitem_link: Collega due work item tra loro (es. Parent/Child, correlati, duplicati).

Integrazione Git

• git_repos: Elenca i repository Git presenti nel progetto configurato.

• git_file: Legge il contenuto di un file direttamente da un repository e da un ramo specifico (default: main).

• git_push: Consente di effettuare commit/push di modifiche (aggiunta, modifica, eliminazione di file) direttamente sul server remoto.

• git_pr_create: Crea una nuova Pull Request.

• git_pr_get: Legge lo stato e i dettagli di una specifica Pull Request.

• git_pr_update: Modifica lo stato di una Pull Request (es. impostandolo su completed, abandoned, active).

• git_pr_comment_create: Crea discussioni/commenti specifici per la revisione del codice su righe precise di un file in una PR.

• git_pr_comment_list: Elenca tutti i thread e commenti relativi a una PR.

Monitoraggio Pipelines

• pipeline_run: Avvia una pipeline specificando eventuali variabili di runtime.

• pipeline_get: Recupera lo stato di avanzamento di una specifica esecuzione.

• pipeline_logs: Estrae i log combinati di un'esecuzione per facilitare il debugging.

Ricerca Utenti

• identity_search: Cerca utenti o gruppi all'interno della directory DevOps per nome o email.

Requisiti

• Node.js (versione 18 o superiore)

• npm (incluso nell'installazione di Node.js)

Installazione tramite Smithery

Per installare automaticamente Azure DevOps MCP Server per Claude Desktop tramite Smithery:

npx -y @smithery/cli install github-y8ge/mcp-azure-devops --client claude

Installazione Manuale

1. Installa Node.js 18 o superiore (include npm).

2. Clona il repository e installa le dipendenze:

   git clone https://github.com/varnierg/MCP-for-AZURE-Devops.git
   cd MCP-for-AZURE-Devops
   npm install

3. Il server compilato (dist/index.js) è già incluso. Ricompila solo se modifichi i sorgenti TypeScript:

   npm run build

Configurazione

Il server necessita dell'organizzazione Azure DevOps (o di un URL di progetto/dashboard), dell'email/username utente e di un Personal Access Token (PAT) di Azure DevOps.

Generare un PAT in Azure DevOps

1. Accedi al tuo portale Azure DevOps.

2. In alto a destra, clicca sull'icona delle impostazioni utente e seleziona Personal Access Tokens.

3. Clicca su New Token.

4. Seleziona i permessi necessari (scopi). Per utilizzare tutti gli strumenti del server MCP, si raccomandano i seguenti permessi:

   • Code: Read & Write (necessario per push, pull request e lettura dei file)

   • Work Items: Read & Write (necessario per gestire i task e i bug)

   • Build: Read & Execute (se desideri avviare ed esaminare i log delle pipeline)

   • Graph: Read (necessario per cercare identità e utenti)

5. Copia il token generato (non sarà più visibile successivamente).

Come fornire le credenziali (scegline una)

• A runtime (predefinito): l'assistente IA chiama connection_configure con URL, username e PAT alla prima connessione a un'organizzazione. Le credenziali vengono cifrate e salvate localmente.

• Configurazione guidata: esegui npm run setup e inserisci URL del progetto, username e PAT. Lo script verifica la connessione prima di salvare.

• Argomenti di avvio / variabili d'ambiente: --org, --username, --pat, --project, oppure AZURE_DEVOPS_ORG, AZURE_DEVOPS_USERNAME, AZURE_DEVOPS_PAT, AZURE_DEVOPS_PROJECT.

Avvio ed Utilizzo

Configurazione nei client AI (stdio)

Aggiungi il server alla configurazione MCP del tuo client. Esempio per Claude Desktop (%APPDATA%\Claude\claude_desktop_config.json su Windows, ~/Library/Application Support/Claude/claude_desktop_config.json su macOS):

{
  "mcpServers": {
    "mcp-azure-devops": {
      "command": "node",
      "args": [
        "C:\\Percorso\\Della\\Cartella\\MCP-for-AZURE-Devops\\dist\\index.js"
      ]
    }
  }
}

Nota: sostituisci il percorso con quello assoluto del repository clonato (su macOS/Linux ad es. /Users/<utente>/MCP-for-AZURE-Devops/dist/index.js). Lo stesso blocco command + args funziona anche negli altri client stdio (Antigravity, Cursor, VS Code, …).

Modalità Remota (HTTP)

Il server può esporre gli stessi strumenti anche via HTTP, così un'unica istanza può essere condivisa da più client o eseguita in un container. Guida completa (in inglese): Remote HTTP Mode (wiki).

Avvio: node dist/index.js --port 8080 (oppure PORT / MCP_PORT; su Linux/macOS e nei container la porta predefinita è 8080). Il trasporto stdio resta comunque attivo.

Indirizzo di ascolto: 127.0.0.1 per impostazione predefinita (solo client locali). Per accettare connessioni da altre macchine usa --host 0.0.0.0 o MCP_HOST=0.0.0.0 (l'immagine Docker lo imposta già) e attiva l'autenticazione.

Autenticazione dell'endpoint MCP (combinabili):

Senza nessuna di queste opzioni il server funziona in modalità aperta (solo per localhost/test). Più di 5 tentativi di autenticazione falliti (con un header Authorization non valido) da uno stesso IP in 10 minuti bloccano quell'IP per 30 minuti; le sonde di discovery OAuth prive di autenticazione restituiscono 401 WWW-Authenticate senza essere conteggiate nel blocco. Un token Entra ID emesso per Azure DevOps viene usato anche per chiamare Azure DevOps per conto dell'utente, senza bisogno di PAT.

Credenziali Azure DevOps:

• Per sessione / per utente autenticato (multi-utente): header X-Azure-DevOps-Org, X-Azure-DevOps-PAT, X-Azure-DevOps-Username, X-Azure-DevOps-Project (consigliati), oppure parametri query organization, pat, … / config=<JSON base64> (formato Smithery). connection_configure mantiene le credenziali solo in memoria (mai su disco); quando si accede tramite Microsoft OAuth è sufficiente passare url (ometti token per usare la sessione OAuth, oppure fornisci un PAT personalizzato per connetterti con un'altra utenza DevOps). Per le richieste autenticate (UPN Microsoft Entra ID o Bearer token), le credenziali in memoria vengono inoltre mantenute per singolo utente autenticato (TTL di 12 ore), così i client MCP HTTP stateless che aprono una nuova sessione per ogni chiamata agli strumenti mantengono organizzazione e progetto configurati. Le sessioni Mcp-Session-Id inattive da più di 30 minuti vengono eliminate.

• Globali (utente singolo): AZURE_DEVOPS_ORG, AZURE_DEVOPS_PAT, AZURE_DEVOPS_USERNAME, AZURE_DEVOPS_PROJECT. In questo caso l'autenticazione è obbligatoria.

Docker (locale):

docker build -t mcp-azure-devops .
docker run -p 8080:8080 -e MCP_AUTH_TOKEN=un-segreto-lungo-e-casuale mcp-azure-devops
# Endpoint client: http://localhost:8080/mcp

Configurazione del client (client con supporto remoto; la chiave può essere url o serverUrl a seconda del client):

{
  "mcpServers": {
    "azure-devops": {
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer un-segreto-lungo-e-casuale",
        "X-Azure-DevOps-Org": "my-org",
        "X-Azure-DevOps-PAT": "<il-tuo-pat>"
      }
    }
  }
}

Per i client solo stdio usa il bridge: npx -y mcp-remote http://localhost:8080/mcp --header "Authorization: Bearer un-segreto-lungo-e-casuale".

Test di Autovalutazione

Per verificare il corretto funzionamento dei moduli interni (parsing degli URL, crittografia locale, configuration store, ricerca nel database offline), puoi eseguire la suite di test integrata:

npm run test

Configurazione dell'Ambiente di Test / Creazione dei Dati di Test

Per testare gli strumenti MCP di Azure DevOps (Work Item, Git, Pipeline e Identità), puoi configurare un ambiente sandbox dedicato:

1. Creare un'Organizzazione di Test: Accedi a dev.azure.com e crea un'organizzazione personale gratuita (es. my-sandbox-org).

2. Creare un Progetto di Test: All'interno dell'organizzazione, crea un nuovo progetto privato (es. TestProject).

3. Popolare i Dati di Test:

   • Repository Git: Inizializza il repository predefinito con un ramo main e aggiungi alcuni file di esempio (es. README.md, index.html) per testare gli strumenti Git.

   • Work Items: Crea un paio di Work Item di esempio (es. un Bug intitolato "Test Bug" e un Task intitolato "Test Task") per testare la visualizzazione e modifica dei task.

   • Pipeline: Configura una pipeline di base (es. usando un semplice template YAML "Starter pipeline") per testare l'avvio delle pipeline e il recupero dei log.

   • Identità: Aggiungi almeno un altro utente o gruppo nelle impostazioni del progetto per testare lo strumento di ricerca identità.