Skip to content

Latest commit

 

History

History
329 lines (227 loc) · 11.5 KB

GETTINGSTARTED.md

File metadata and controls

329 lines (227 loc) · 11.5 KB

🚀 Getting Started with Azure DevOps MCP Server

This guide will help you get started with the Azure DevOps MCP Server in different environments.

🕐 Prerequisites

For the best experience, use Visual Studio Code and GitHub Copilot.

Before you begin, make sure you have:

For Visual Studio Code

  1. Install VS Code or VS Code Insiders
  2. Install Node.js 20+
  3. Open VS Code in an empty folder

For Visual Studio 2022

  1. Install VS Studio 2022 version 17.14 or later
  2. Open a project in Visual Studio

🍕 Installation Options

➡️ Visual Studio Code & GitHub Copilot

For the best experience, use Visual Studio Code and GitHub Copilot.

✨ One-Click Install

Install with NPX in VS Code Install with NPX in VS Code Insiders

After installation, select GitHub Copilot Agent Mode and refresh the tools list. Learn more about Agent Mode in the VS Code Documentation.

🧨 Install from Public Feed (Recommended)

This installation method is the easiest for all users of Visual Studio Code.

🎥 Watch this quick start video to get up and running in under two minutes!

Steps

In your project, add a .vscode\mcp.json file with the following content:

{
  "inputs": [
    {
      "id": "ado_org",
      "type": "promptString",
      "description": "Azure DevOps organization name  (e.g. 'contoso')"
    }
  ],
  "servers": {
    "ado": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@azure-devops/mcp", "${input:ado_org}"]
    }
  }
}

Save the file, then click 'Start'.

start mcp server

In chat, switch to Agent Mode.

Click "Select Tools" and choose the available tools.

configure mcp server tools

💥 We strongly recommend creating a .github\copilot-instructions.md in your project and copying the contents from this copilot-instructions.md file. This will enhance your experience using the Azure DevOps MCP Server with GitHub Copilot Chat.

Start using it
  1. Open GitHub Copilot in VS Code and switch to Agent mode.
  2. Start the Azure DevOps MCP Server.
  3. The server appears in the tools list.
  4. Try prompts like "List ADO projects".
Using Token Authentication via Environment Variables

For automated scenarios or when you want to use a token stored in an environment variable, you can use the envvar authentication type:

  1. Set your token in the ADO_MCP_AUTH_TOKEN environment variable:

    export ADO_MCP_AUTH_TOKEN="your-azure-devops-token"

  2. Update your .vscode/mcp.json to use token authentication:

    {
  "inputs": [
    {
      "id": "ado_org",
      "type": "promptString",
      "description": "Azure DevOps organization name (e.g. 'contoso')"
    }
  ],
  "servers": {
    "ado": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@azure-devops/mcp", "${input:ado_org}", "--authentication", "envvar"]
    }
  }
}

This approach is particularly useful for CI/pipeline scenarios or when you want to avoid interactive authentication and use another credential source.

🛠️ Install from Source (Dev Mode)

This installation method is recommended for advanced users and contributors who want immediate access to the latest updates from the main branch. It is ideal if you are developing new tools, enhancing existing features, or maintaining a custom fork.

Note: For most users, installing from the public feed is simpler and preferred. Use the source installation only if you need the latest changes or are actively contributing to the project.

Steps

Clone the repository.

Install dependencies:

npm install

Edit or add .vscode/mcp.json:

{
  "inputs": [
    {
      "id": "ado_org",
      "type": "promptString",
      "description": "Azure DevOps organization's name  (e.g. 'contoso')"
    }
  ],
  "servers": {
    "ado": {
      "type": "stdio",
      "command": "mcp-server-azuredevops",
      "args": ["${input:ado_org}"]
    }
  }
}

Start the Azure DevOps MCP Server.

start mcp server

In chat, switch to Agent Mode.

Click "Select Tools" and choose the available tools.

configure mcp server tools

💥 We strongly recommend creating a .github\copilot-instructions.md in your project and copying the contents from this copilot-instructions.md file. This will help you get the best experience using the Azure DevOps MCP Server in GitHub Copilot Chat.

➡️ Visual Studio 2022 & GitHub Copilot

🧨 Install from Public Feed (Recommended)

This installation method is the easiest for all users of Visual Studio 2022.

🎥 Watch this quick start video to get up and running in under two minutes!

Steps

Add a .mcp.json file to the solution folder with the following content:

{
  "inputs": [
    {
      "id": "ado_org",
      "type": "promptString",
      "description": "Azure DevOps organization name  (e.g. 'contoso')"
    }
  ],
  "servers": {
    "ado": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@azure-devops/mcp", "${input:ado_org}"]
    }
  }
}

Save the file.

Add your organization name by clicking on the input option.

start mcp server from visual studio 2022

Open Copilot chat and switch to Agent Mode.

Click the "Tools" icon and choose the available tools.

set tools to use in visual studio 2022

💥 We strongly recommend creating a .github\copilot-instructions.md in your project and copying the contents from this copilot-instructions.md file. This will enhance your experience using the Azure DevOps MCP Server with GitHub Copilot Chat.

Start using it

Prerequisites: Visual Studio 2022 v17.14+, Agent mode enabled in Tools > Options > GitHub > Copilot > Copilot Chat.

  1. Switch to Agent mode in the Copilot Chat window.
  2. Enter your Azure DevOps organization name.
  3. Select desired ado tools.
  4. Try prompts like "List ADO projects".

For more details, see Visual Studio MCP Servers documentation and the Getting Started Video.

💻 Using MCP Server with GitHub Copilot CLI

Use the Copilot CLI to interactively add the MCP server:

/mcp add

Alternatively, create or edit the configuration file ~/.copilot/mcp-config.json and add:

{
  "mcpServers": {
    "ado": {
      "command": "npx",
      "args": ["-y", "@azure-devops/mcp", "{Contoso}"],
      "tools": ["*"]
    }
  }
}

Replace {Contoso} with your Azure DevOps organization name.

For more information, see the Copilot CLI documentation.

🤖 Using MCP Server with Claude Code

See https://docs.anthropic.com/en/docs/claude-code/mcp for general guidance on adding MCP Server to Claude Code experience.

For the Azure DevOps MCP Server, use the following command:

claude mcp add azure-devops -- npx -y @azure-devops/mcp Contoso

Replace Contoso with your own organization name

✴️ Using MCP Server with Claude Desktop

Open Claude Desktop and navigate to File > Settings > Developer. Click Edit Config.

Configuring MCP servers in Claude Desktop

Open the configuration file in your preferred editor (e.g., VS Code) and add the following JSON:

{
  "mcpServers": {
    "ado": {
      "command": "npx",
      "args": ["-y", "@azure-devops/mcp", "{Contoso}"]
    }
  }
}

Replace {Contoso} with your Azure DevOps organization name. Save the file and perform a hard restart of the Claude app.

Start a new chat, then click the Search and Tools icon. The ado toolset should now be available.

ADO tools in Claude Desktop

You’re ready to start using the Azure DevOps MCP Server in Claude Desktop. Try a simple request such as: get list of ado projects.

For additional guidance on Claude Desktop, see the Quickstart.

🍇 Using MCP Server with Cursor

To integrate the Azure DevOps MCP Server with Cursor, create a .cursor\mcp.json file and add your Azure DevOps organization to the mcpServers list.

{
  "mcpServers": {
    "ado": {
      "command": "npx",
      "args": ["-y", "@azure-devops/mcp", "{Contoso}"]
    }
  }
}

Replace {Contoso} with your actual Azure DevOps organization name.

Save the file, and when Cursor detects the MCP Server, click Enable.

enable mcp server from cursor

Start the Azure DevOps MCP Server

Open the terminal and start the MCP Server with:

npx -y @azure-devops/mcp {Contoso}

Replace Contoso with your Azure DevOps organization.

You can now use the Azure DevOps MCP Server tools directly in chat.

📽️ Azure DevOps MCP Server: Getting started with Cursor