For Azure Devops Boards

CI - PR - Build & Test CD - Tag - Build & Release

A Model Context Protocol (MCP) server for interacting with Azure DevOps Boards and Work Items, written in Rust.

Features

• Work Item Management: Create, update, get, and query work items.

• Board Integration: List teams, boards, and fetch board items.

• WIQL Support: Run custom WIQL queries.

• Simplified Output: Optimized JSON output for LLM consumption (reduced token usage).

Installation

Check out the section MCP Configuration for how to configure your preferred AI (MCP) client.

macOS (Homebrew)

brew tap danielealbano/mcp-tools
brew install mcp-for-azure-devops-boards

The path to the binary will be /opt/homebrew/bin/mcp-for-azure-devops-boards.

Windows (Scoop)

scoop bucket add mcp-tools https://github.com/danielealbano/scoop-mcp-tools
scoop install mcp-for-azure-devops-boards

The path to the binary will be %USERPROFILE%\scoop\apps\mcp-for-azure-devops-boards\current\mcp-for-azure-devops-boards.exe.

Configuration

Setting	Description	CLI Flag	Env Variable
Server Mode	Run as HTTP server instead of stdio	--server	N/A
Port	Port for HTTP server (default: 3000)	--port	N/A

Note: If --server is not specified, the software will run in stdio mode.

Authentication

This server leverages standard Azure authentication mechanisms to query Azure DevOps. On every request it acquires a Bearer token for the Azure DevOps REST API (scope 499b84ac-1321-427f-aa17-267ca6975798/.default) by trying the following credential sources in order and using the first one that returns a token:

1. Environment (client secret) — used only when AZURE_TENANT_ID, AZURE_CLIENT_ID, and AZURE_CLIENT_SECRET are all set. If only some are set, it is skipped with a warning.
2. Azure CLI — runs az account get-access-token for the Azure DevOps scope, using your az login session.
3. Azure Developer CLI — uses your azd auth login session.
4. Managed identity — for Azure-hosted deployments. Off Azure this probe is unreachable, so it is bounded by a 2-second timeout and then skipped, ensuring the chain never hangs.

If all sources fail, the returned error lists each source's failure so you can see exactly why (for example, an Azure CLI consent error alongside "azd not found on PATH"), rather than only the last one tried.

For local development, signing in with the Azure CLI (below) is the simplest option — you must have run az login with access to the target Azure DevOps organization.

Installing Azure CLI

If you don't have the Azure CLI installed:

macOS (Homebrew):

brew install azure-cli

Windows (Scoop):

scoop install azure-cli

Windows (Chocolatey):

choco install azure-cli

For other installation methods, see the official Azure CLI installation guide.

Logging In

To authenticate, run:

az login

Usage

Stdio Mode (Default)

This is the standard mode for MCP clients (like Claude Desktop or Cursor). This mode is preferred for security as it ensures no credentials are shared over the network.

path/to/mcp-for-azure-devops-boards

HTTP Server Mode

You can also run it as an HTTP server (SSE). Note that in this mode, the server listens on 0.0.0.0 (all interfaces).

path/to/mcp-for-azure-devops-boards --server --port 3000

MCP Configuration

Note: Make sure you have run az login in your terminal so the process can pick up the credentials.

Quick setup with --install

The fastest way to register the MCP server with your preferred client:

mcp-for-azure-devops-boards --install <target>

Valid targets and where each writes its configuration:

Target	Config file	Scope
claude-code	~/.claude.json	Global (home)
claude-desktop	macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json	Global (per-user)
cursor	~/.cursor/mcp.json	Global (home)
vscode	.vscode/mcp.json	Workspace (current directory)
codex	~/.codex/config.toml	Global (home)
gemini-cli	~/.gemini/settings.json	Global (home)

The command auto-detects the binary path, resolves the correct config file location, and writes the entry in the expected format. Existing configuration is preserved.

Manual configuration

Claude Code

Config file: ~/.claude.json

{
  "mcpServers": {
    "mcp-for-azure-devops-boards": {
      "command": "/opt/homebrew/bin/mcp-for-azure-devops-boards"
    }
  }
}

Windows (Scoop): Replace the command path with %USERPROFILE%\\scoop\\apps\\mcp-for-azure-devops-boards\\current\\mcp-for-azure-devops-boards.exe.

Claude Desktop

Config file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mcp-for-azure-devops-boards": {
      "command": "/opt/homebrew/bin/mcp-for-azure-devops-boards"
    }
  }
}

Windows (Scoop): Replace the command path with %USERPROFILE%\\scoop\\apps\\mcp-for-azure-devops-boards\\current\\mcp-for-azure-devops-boards.exe.

Cursor

Config file: ~/.cursor/mcp.json

{
  "mcpServers": {
    "mcp-for-azure-devops-boards": {
      "command": "/opt/homebrew/bin/mcp-for-azure-devops-boards"
    }
  }
}

Windows (Scoop): Replace the command path with %USERPROFILE%\\scoop\\apps\\mcp-for-azure-devops-boards\\current\\mcp-for-azure-devops-boards.exe.

VS Code

Config file: .vscode/mcp.json (workspace level)

{
  "servers": {
    "mcp-for-azure-devops-boards": {
      "type": "stdio",
      "command": "/opt/homebrew/bin/mcp-for-azure-devops-boards"
    }
  }
}

Windows (Scoop): Replace the command path with %USERPROFILE%\\scoop\\apps\\mcp-for-azure-devops-boards\\current\\mcp-for-azure-devops-boards.exe.

gemini-cli

Config file: ~/.gemini/settings.json

{
  "mcpServers": {
    "mcp-for-azure-devops-boards": {
      "command": "/opt/homebrew/bin/mcp-for-azure-devops-boards"
    }
  }
}

Windows (Scoop): Replace the command path with %USERPROFILE%\\scoop\\apps\\mcp-for-azure-devops-boards\\current\\mcp-for-azure-devops-boards.exe.

Codex CLI

Config file: ~/.codex/config.toml

[mcp_servers.mcp-for-azure-devops-boards]
command = "/opt/homebrew/bin/mcp-for-azure-devops-boards"

Windows (Scoop): Replace the command path with %USERPROFILE%\\scoop\\apps\\mcp-for-azure-devops-boards\\current\\mcp-for-azure-devops-boards.exe.

Available Tools

This software is currently in development. The tools and their parameters are subject to change.

The server exposes the following tools for MCP clients.

The general structure of the tool names is azdo_VERB_WHAT (e.g., azdo_list_teams, azdo_get_work_item).

Discovery

• azdo_list_organizations: List all Azure DevOps organizations the authenticated user has access to.
  • Required: None (uses authenticated user's credentials)
• azdo_list_projects: List all projects in an Azure DevOps organization.
  • Required: organization

Work Items

Note: All work item tools require organization and project parameters.

• azdo_create_work_item: Create a new work item.
  • Required: organization, project, work_item_type, title
  • Optional: description, assigned_to, area_path, iteration_path, state, board_column, board_row, priority, severity, story_points, effort, remaining_work, tags, activity, parent_id, start_date, target_date, acceptance_criteria, repro_steps, fields (JSON string for custom fields).
• azdo_update_work_item: Update an existing work item.
  • Required: organization, project, id
  • Optional: All fields available in creation.
• azdo_get_work_item: Get details of a specific work item.
  • Required: organization, project, id
  • Optional: include_latest_n_comments (number of recent comments to include, -1 for all)
• azdo_get_work_items: Get multiple work items by their IDs.
  • Required: organization, project, ids (array of work item IDs)
  • Optional: include_latest_n_comments (number of recent comments to include, -1 for all)
• azdo_query_work_items: Query work items using structured filters.
  • Required: organization, project
  • Optional Filters: area_path, iteration_path, created_date_from/to, modified_date_from/to.
  • Inclusion Lists: include_board_column, include_board_row, include_work_item_type, include_state, include_assigned_to, include_tags.
  • Exclusion Lists: exclude_board_column, exclude_board_row, exclude_work_item_type, exclude_state, exclude_assigned_to, exclude_tags.
  • Optional: include_latest_n_comments (number of recent comments to include, -1 for all)
• azdo_query_work_items_by_wiql: Execute a raw WIQL (Work Item Query Language) query.
  • Required: organization, project, query
  • Optional: include_latest_n_comments (number of recent comments to include, -1 for all)
• azdo_add_comment: Add a comment to a work item.
  • Required: organization, project, work_item_id, text
• azdo_link_work_items: Create a relationship between two work items.
  • Required: organization, project, source_id, target_id, link_type (Parent, Child, Related, Duplicate, Dependency).

Boards & Teams

Note: All board and team tools require organization and project parameters.

• azdo_list_teams: List all teams in the project.
  • Required: organization, project
• azdo_get_team: Get details of a specific team.
  • Required: organization, project, team_id
• azdo_list_team_boards: List boards for a specific team.
  • Required: organization, project, team_id
• azdo_get_team_board: Get details of a specific board.
  • Required: organization, project, team_id, board_id
• azdo_list_work_item_types: List all available work item types in the project.
  • Required: organization, project
• azdo_list_tags: List all tags in use in the project.
  • Required: organization, project
• azdo_get_team_current_iteration: Get the current active iteration/sprint for a team.
  • Required: organization, project, team_id
• azdo_get_team_iterations: Get all iterations/sprints for a team.
  • Required: organization, project, team_id

Contributing

We welcome contributions!

1. Fork the repository.
2. Create a new branch for your feature or bugfix (git checkout -b feature/amazing-feature).
3. Commit your changes.
4. Push to your branch.
5. Open a Pull Request.

Building from Source

Prerequisites

• Rust (latest stable version)
• Azure CLI (required for local authentication)

Steps

1. Clone the repository:

   git clone https://github.com/danielealbano/mcp-for-azure-devops-boards.git
   cd mcp-for-azure-devops-boards
   

2. Build the project:

   cargo build --release
   

Tooling

• Run tests: cargo test
• Check code style: cargo fmt --check
• Linting: cargo clippy

Disclaimer

This project is not affiliated with, endorsed by, or sponsored by Microsoft. Azure, Azure DevOps, and related trademarks are the property of their respective owners. This software uses standard Microsoft's services APIs to interact with Azure and Microsoft Graph, among other services.

License

This project is licensed under the MIT License - see the LICENSE.md file for details.