@fsabatini82/azure-devops-mcp

v2.3.5

Published

4 months ago

MCP server for interacting with Azure DevOps with PAT authentication and cache control support

0High
0Medium
0Low

fsabatini82

azure-devops mcp model-context-protocol azure devops pat authentication

⭐ Azure DevOps MCP Server (Enhanced)

Enhanced Azure DevOps MCP Server with Personal Access Token (PAT) authentication support.

✨ New in v2.3.5

🔄 Cache Control: --no-cache parameter for fresh authentication
🛡️ Enhanced PAT Support: Fresh token reading on environment changes
🧪 Comprehensive Testing: Added no-cache functionality tests
📚 Improved Documentation: Cache troubleshooting guides
🚀 VS Code Integration: Better caching issue resolution

Previous Releases

v2.3.4

🔐 PAT Authentication: Secure token-based authentication
🛡️ Enhanced Security: Comprehensive security guidelines
🧪 Robust Testing: Complete test coverage
📚 Better Documentation: Clear setup instructions
🚀 Independent Distribution: Ready for npm publishing
✅ Package Alignment: Fixed package-lock.json synchronization

🚀 Quick Install

npx @fsabatini82/azure-devops-mcp@latest your-org-name --authentication pat

VS Code Installation

This TypeScript project provides a local MCP server for Azure DevOps, enabling you to perform a wide range of Azure DevOps tasks directly from your code editor.

📄 Table of Contents

📺 Overview

The Azure DevOps MCP Server brings Azure DevOps context to your agents. Try prompts like:

"List my ADO projects"
"List ADO Builds for 'Contoso'"
"List ADO Repos for 'Contoso'"
"List test plans for 'Contoso'"
"List teams for project 'Contoso'"
"List iterations for project 'Contoso'"
"List my work items for project 'Contoso'"
"List work items in current iteration for 'Contoso' project and 'Contoso Team'"
"List all wikis in the 'Contoso' project"
"Create a wiki page '/Architecture/Overview' with content about system design"
"Update the wiki page '/Getting Started' with new onboarding instructions"
"Get the content of the wiki page '/API/Authentication' from the Documentation wiki"

🏆 Expectations

The Azure DevOps MCP Server is built from tools that are concise, simple, focused, and easy to use—each designed for a specific scenario. We intentionally avoid complex tools that try to do too much. The goal is to provide a thin abstraction layer over the REST APIs, making data access straightforward and letting the language model handle complex reasoning.

⚙️ Supported Tools

Interact with these Azure DevOps services:

🧿 Core

core_list_project_teams: Retrieve a list of teams for the specified Azure DevOps project.
core_list_projects: Retrieve a list of projects in your Azure DevOps organization.
core_get_identity_ids: Retrieve Azure DevOps identity IDs for a list of unique names.

⚒️ Work

work_list_team_iterations: Retrieve a list of iterations for a specific team in a project.
work_create_iterations: Create new iterations in a specified Azure DevOps project.
work_assign_iterations: Assign existing iterations to a specific team in a project.

📅 Work Items

wit_my_work_items: Retrieve a list of work items relevant to the authenticated user.
wit_list_backlogs: Retrieve a list of backlogs for a given project and team.
wit_list_backlog_work_items: Retrieve a list of backlogs for a given project, team, and backlog category.
wit_get_work_item: Get a single work item by ID.
wit_get_work_items_batch_by_ids: Retrieve a list of work items by IDs in batch.
wit_update_work_item: Update a work item by ID with specified fields.
wit_create_work_item: Create a new work item in a specified project and work item type.
wit_list_work_item_comments: Retrieve a list of comments for a work item by ID.
wit_get_work_items_for_iteration: Retrieve a list of work items for a specified iteration.
wit_add_work_item_comment: Add a comment to a work item by ID.
wit_add_child_work_items: Create one or more child work items of a specific work item type for the given parent ID.
wit_link_work_item_to_pull_request: Link a single work item to an existing pull request.
wit_get_work_item_type: Get a specific work item type.
wit_get_query: Get a query by its ID or path.
wit_get_query_results_by_id: Retrieve the results of a work item query given the query ID.
wit_update_work_items_batch: Update work items in batch.
wit_work_items_link: Link work items together in batch.
wit_work_item_unlink: Unlink one or many links from a work item.
wit_add_artifact_link: Link to artifacts like branch, pull request, commit, and build.

📁 Repositories

repo_list_repos_by_project: Retrieve a list of repositories for a given project.
repo_list_pull_requests_by_repo_or_project: Retrieve a list of pull requests for a given repository or project.
repo_list_branches_by_repo: Retrieve a list of branches for a given repository.
repo_list_my_branches_by_repo: Retrieve a list of your branches for a given repository ID.
repo_list_pull_requests_by_commits: List pull requests associated with commits.
repo_list_pull_request_threads: Retrieve a list of comment threads for a pull request.
repo_list_pull_request_thread_comments: Retrieve a list of comments in a pull request thread.
repo_get_repo_by_name_or_id: Get the repository by project and repository name or ID.
repo_get_branch_by_name: Get a branch by its name.
repo_get_pull_request_by_id: Get a pull request by its ID.
repo_create_pull_request: Create a new pull request.
repo_create_branch: Create a new branch in the repository.
repo_update_pull_request: Update various fields of an existing pull request (title, description, draft status, target branch).
repo_update_pull_request_reviewers: Add or remove reviewers for an existing pull request.
repo_reply_to_comment: Replies to a specific comment on a pull request.
repo_resolve_comment: Resolves a specific comment thread on a pull request.
repo_search_commits: Searches for commits.
repo_create_pull_request_thread: Creates a new comment thread on a pull request.

🚀 Pipelines

pipelines_get_build_definitions: Retrieve a list of build definitions for a given project.
pipelines_get_build_definition_revisions: Retrieve a list of revisions for a specific build definition.
pipelines_get_builds: Retrieve a list of builds for a given project.
pipelines_get_build_log: Retrieve the logs for a specific build.
pipelines_get_build_log_by_id: Get a specific build log by log ID.
pipelines_get_build_changes: Get the changes associated with a specific build.
pipelines_get_build_status: Fetch the status of a specific build.
pipelines_update_build_stage: Update the stage of a specific build.
pipelines_get_run: Gets a run for a particular pipeline.
pipelines_list_runs: Gets top 10000 runs for a particular pipeline.
pipelines_run_pipeline: Starts a new run of a pipeline.

Advanced Security

advsec_get_alerts: Retrieve Advanced Security alerts for a repository.
advsec_get_alert_details: Get detailed information about a specific Advanced Security alert.

🧪 Test Plans

testplan_create_test_plan: Create a new test plan in the project.
testplan_create_test_case: Create a new test case work item.
testplan_add_test_cases_to_suite: Add existing test cases to a test suite.
testplan_list_test_plans: Retrieve a paginated list of test plans from an Azure DevOps project. Allows filtering for active plans and toggling detailed information.
testplan_list_test_cases: Get a list of test cases in the test plan.
testplan_show_test_results_from_build_id: Get a list of test results for a given project and build ID.
testplan_create_test_suite: Creates a new test suite in a test plan.

📖 Wiki

wiki_list_wikis: Retrieve a list of wikis for an organization or project.
wiki_get_wiki: Get the wiki by wikiIdentifier.
wiki_list_pages: Retrieve a list of wiki pages for a specific wiki and project.
wiki_get_page: Retrieve wiki page metadata by path.
wiki_get_page_content: Retrieve wiki page content by wikiIdentifier and path.
wiki_create_or_update_page: Create or update wiki pages with full content support.

🔎 Search

search_code: Get code search results for a given search text.
search_wiki: Get wiki search results for a given search text.
search_workitem: Get work item search results for a given search text.

🔌 Installation & Getting Started

For the best experience, use Visual Studio Code and GitHub Copilot. See the getting started documentation to use our MCP Server with other tools such as Visual Studio 2022, Claude Code, and Cursor.

Prerequisites

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

Installation

✨ One-Click Install

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

Authentication Options

The server supports multiple authentication modes. By default it uses an interactive Microsoft login (OAuth). You can explicitly pick a mode via the --authentication (or -a) argument when launching the server (e.g. through your mcp.json args array, before any domain flags).

Supported values:

| Mode | Description | When to use | | ----------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | oauth (default) | Interactive browser login using MSAL. | You want a one‑time sign in and token caching. | | azcli | Uses Azure CLI / DefaultAzureCredential chain. | You are already signed in with az login and prefer CLI token reuse or need multi‑tenant support. | | env | Uses environment credentials (DefaultAzureCredential). | Running in CI or you have managed identity / service principal environment variables set. | | pat | Uses an Azure DevOps Personal Access Token (PAT) provided via env var. | Non-interactive automation or minimal permission scopes. |

Using a Personal Access Token (PAT)

📋 Note: PAT authentication support was added in version 2.3.0

Create a PAT in Azure DevOps (User Settings → Personal Access Tokens). Give it only the scopes you need (for most read scenarios: Code (Read), Work Items (Read), etc.).
Set one of the supported environment variables before starting the server (first match wins):
- AZDO_PAT (preferred)
- ADO_PAT
- AZURE_DEVOPS_EXT_PAT
Launch the server with --authentication pat.

Example mcp.json snippet using PAT:

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

Security notes:

Treat the PAT like a password; never commit it.
Prefer the narrowest scopes possible.
Rotate long‑lived PATs on a schedule.
For interactive local use prefer oauth or azcli to avoid storing PATs.

If the PAT is missing when pat mode is requested, the server will fail fast with a clear error message indicating which environment variables are checked. The PAT is automatically trimmed of whitespace, and empty values after trimming are rejected.

🔄 Cache Control

📋 Note: Cache control support was added in version 2.3.4

By default, VS Code may cache authentication tokens and other MCP server data between sessions. If you need to force fresh authentication (e.g., when changing PAT tokens or switching environments), you can use the --no-cache parameter.

When to use --no-cache:

After updating your PAT token in environment variables
When switching between different Azure DevOps organizations
When experiencing authentication issues after environment changes
For debugging authentication problems

Usage examples:

With PAT authentication:

{
  "servers": {
    "AzureDevOps_withPAT": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@fsabatini82/azure-devops-mcp@latest", "${input:ado_org}", "--authentication", "pat", "--no-cache"]
    }
  }
}

With OAuth authentication:

{
  "servers": {
    "AzureDevOps_OAuth": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@fsabatini82/azure-devops-mcp@latest", "${input:ado_org}", "--authentication", "oauth", "--no-cache"]
    }
  }
}

Performance considerations:

Using --no-cache will slightly increase startup time as tokens need to be refreshed
For production use, only enable --no-cache when necessary
Consider using --no-cache temporarily and removing it once authentication is working correctly

🧨 Install from Public Feed (Recommended)

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

Steps

Create Configuration File

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": {
    "AzureDevOps_withPAT": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@fsabatini82/azure-devops-mcp@latest", "${input:ado_org}", "--authentication", "pat"]
    },
    "AzureDevOps_withPAT_NoCache": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@fsabatini82/azure-devops-mcp@latest", "${input:ado_org}", "--authentication", "pat", "--no-cache"],
      "description": "Use this configuration if you experience caching issues with PAT tokens"
    }
  }
}

Set Your PAT

# Set your Azure DevOps Personal Access Token
$env:AZDO_PAT = "your-pat-token-here"

Start the Server

Save the mcp.json file
Press Ctrl+Shift+P in VS Code
Type "MCP: Restart Servers"
Choose either AzureDevOps_withPAT (default) or AzureDevOps_withPAT_NoCache (for cache issues)
Your enhanced Azure DevOps server will be available!

💡 Tip: If you encounter authentication issues after changing your PAT token, try using the AzureDevOps_withPAT_NoCache configuration to force fresh authentication.

🔄 Version Options

@latest (recommended): Always gets the newest features and security updates
@2.3.4: Pins to a specific version for stability
@^2.3.0: Gets patch updates automatically but not minor updates

For most users, @latest ensures you always have the latest PAT authentication features and security improvements.