Azure DevOps MCP Server

A Model Context Protocol (MCP) server that enables Claude to interact with Azure DevOps work items, projects, and boards directly through natural language.

Version 2.2.0 - Now with 30 tools including work item relationship management

🎯 Features

• Project Management

  • List all projects in your Azure DevOps organization
  • Get detailed project information and statistics

• Sprint & Iteration Management 🆕

  • List all iterations/sprints in a project
  • Get the current active sprint
  • View work items in specific iterations
  • Move work items between sprints
  • Get detailed iteration statistics

• Work Item Operations

  • Query work items using WIQL or predefined shortcuts
  • Create new work items (Tasks, Bugs, User Stories, Features, Epics, Issues)
  • Update existing work items (title, state, assignee, description)
  • Add comments and discussions to work items
  • Get detailed work item information

• Personal Productivity

  • List all work items assigned to you
  • View items organized by state
  • Include recently completed items
  • Use smart query shortcuts (my-items, my-bugs, my-tasks, recent)

• Work Item Relationships 🆕

  • Add relationships between work items (Parent/Child, Related, Dependencies)
  • Remove relationships between work items
  • View all relationships for a work item
  • List available relationship types
  • Build work item hierarchies (Epic → Feature → Story → Task)
  • Track dependencies and mark duplicates

📋 Prerequisites

Before installing this MCP server, ensure you have:

1. Node.js (v18.0.0 or higher)

   node --version  # Should output v18.0.0 or higher

2. Azure CLI installed and configured

   # Install Azure CLI (if not already installed)
   # macOS
   brew install azure-cli
   
   # Windows
   winget install Microsoft.AzureCLI
   
   # Linux/WSL
   curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

3. Azure DevOps Extension for Azure CLI

   az extension add --name azure-devops

4. Azure Authentication

   # Login to Azure
   az login
   
   # Optional: Set default organization (the tool will auto-configure if not set)
   az devops configure --defaults organization=https://dev.azure.com/YOUR_ORG

🚀 Installation

Option 1: Install from npm (Recommended)

npm install -g @jybrd/azure-devops-mcp

Option 2: Install from Source

# Clone the repository
git clone https://github.com/jaybird-us/azure-devops-mcp.git
cd azure-devops-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Optional: Link globally
npm link

⚙️ Configuration

Claude Desktop Setup

Add the following to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "azure-devops": {
      "command": "npx",
      "args": ["@jybrd/azure-devops-mcp"],
      "env": {
        "AZURE_DEVOPS_ORG": "https://dev.azure.com/YOUR_ORG"
      }
    }
  }
}

For local development installation:

{
  "mcpServers": {
    "azure-devops": {
      "command": "node",
      "args": ["/absolute/path/to/azure-devops-mcp/dist/index.js"],
      "env": {
        "AZURE_DEVOPS_ORG": "https://dev.azure.com/YOUR_ORG"
      }
    }
  }
}

Environment Configuration (Required)

You must configure your Azure DevOps organization in one of two ways:

Option 1: In Claude Desktop config (Recommended)

• Add the "env" section with your organization URL as shown above

Option 2: Via Azure CLI

az devops configure --defaults organization=https://dev.azure.com/YOUR_ORG

🛠️ Available Tools (30 Total)

Categories:

• Work Items (6 tools): Query, create, update, comment on work items
• Discovery (9 tools): Explore fields, types, states, and relationships
• Projects (6 tools): Manage projects, teams, repos, and pipelines
• Iterations (5 tools): Handle sprints and iteration planning
• Relations (4 tools): Manage work item relationships and hierarchies

Note: Query management tools have been removed in v2.1.0 for improved reliability

list_projects

Lists all projects in your Azure DevOps organization with details including name, description, state, and visibility.

query_work_items

Query work items using WIQL or built-in shortcuts:

• "my-items" - All items assigned to you
• "my-bugs" - Bugs assigned to you
• "my-tasks" - Tasks assigned to you
• "recent" - Recently modified items (last 7 days)
• Custom WIQL queries for advanced filtering

Parameters:

• query (required): WIQL query or shortcut name
• project (optional): Limit results to specific project

get_work_item

Retrieve detailed information about a specific work item.

Parameters:

• id (required): Work item ID
• fields (optional): Comma-separated list of specific fields to retrieve

create_work_item

Create a new work item in Azure DevOps.

Parameters:

• type (required): Work item type (Task, Bug, User Story, Feature, Epic, Issue)
• title (required): Work item title
• description (optional): Detailed description
• assigned_to (optional): Assignee email or "@Me"
• tags (optional): Semicolon-separated tags
• project (optional): Target project name

update_work_item

Update an existing work item.

Parameters:

• id (required): Work item ID
• title (optional): New title
• state (optional): New state (New, Active, Resolved, Closed, Removed)
• assigned_to (optional): New assignee
• description (optional): New description
• comment (optional): Add a comment with the update

add_comment

Add a comment to an existing work item.

Parameters:

• id (required): Work item ID
• comment (required): Comment text

list_my_work

List all work items assigned to you, organized by state.

Parameters:

• include_recently_completed (optional): Include items completed in the last 7 days

Sprint & Iteration Tools 🆕

list_iterations

List all iterations/sprints in a project.

Parameters:

• project (required): Project name
• team (optional): Team name
• depth (optional): Depth of iteration tree

get_current_iteration

Get the current active sprint/iteration.

Parameters:

• project (required): Project name
• team (optional): Team name

get_iteration_work_items

Get all work items in a specific iteration.

Parameters:

• project (required): Project name
• iteration (required): Iteration name or path

move_to_iteration

Move a work item to a different iteration/sprint.

Parameters:

• id (required): Work item ID
• iteration (required): Target iteration name
• project (optional): Project name

get_iteration_details

Get detailed information about an iteration including work items grouped by type and state.

Parameters:

• project (required): Project name
• iteration (required): Iteration name

Work Item Relationship Tools 🆕

add_work_item_relation

Add a relationship between work items.

Parameters:

• id (required): Source work item ID
• relation_type (required): Relationship type (e.g., "Parent", "Child", "Related", "Predecessor", "Successor", "Duplicate")
• target_id (optional): Target work item ID(s) - can be single ID or array
• target_url (optional): URL to target work item (alternative to target_id)

remove_work_item_relation

Remove a relationship between work items.

Parameters:

• id (required): Source work item ID
• relation_type (required): Relationship type to remove
• target_id (required): Target work item ID(s) to unlink

get_work_item_relations

Show all relationships for a work item with friendly categorization.

Parameters:

• id (required): Work item ID

list_relation_types

List all available work item relation types in Azure DevOps.

Parameters: None

💬 Usage Examples

Once configured, you can ask Claude:

Work Item Management:

• "List all my Azure DevOps projects"
• "Show me my active work items"
• "Create a new bug titled 'Login page error' in the WebApp project"
• "Add a comment to work item 754 saying 'Fixed in latest commit'"
• "Update task 281 to Completed state"
• "What bugs are assigned to me?"
• "Show me work items that changed this week"

Sprint Management:

• "List all sprints in the WebApp project"
• "What's in our current sprint?"
• "Move task 123 to the next sprint"
• "Show me all work items in Sprint 5"
• "Get details about Sprint 3"

Relationship Management:

• "Add work item 456 as a parent of task 123"
• "Show all relationships for work item 789"
• "Mark work item 101 as a duplicate of 102"
• "Add task 234 as a predecessor to task 567"
• "Remove the relationship between items 333 and 444"
• "What work items are related to epic 100?"
• "List all available relationship types"

🔧 Development

Running from Source

# Install dependencies
npm install

# Run in development mode (with TypeScript)
npm run dev

# Build for production
npm run build

# Run production build
node dist/index.js

Project Structure

azure-devops-mcp/
├── src/
│   └── index.ts         # Main server implementation
├── dist/
│   └── index.js         # Compiled JavaScript (generated)
├── package.json         # Package configuration
├── tsconfig.json        # TypeScript configuration
├── README.md            # This file
└── LICENSE              # MIT license

🐛 Troubleshooting

Common Issues

1. "Error: Cannot find module"

   • Run npm install to install dependencies
   • Ensure you've built the project with npm run build

2. "az: command not found"

   • Install Azure CLI following the prerequisites section
   • Ensure Azure CLI is in your system PATH

3. "ERROR: Access Denied"

   • Run az login to authenticate
   • Verify you have appropriate permissions in Azure DevOps

4. "Organization not configured"

   • The tool will auto-configure, but you can manually set:

   az devops configure --defaults organization=https://dev.azure.com/YOUR_ORG

Debug Mode

To see detailed error messages, run the server directly:

node dist/index.js

📄 License

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

⚠️ Disclaimer

This is an unofficial tool that interfaces with Azure DevOps through the Azure CLI. It is not affiliated with or endorsed by Microsoft Corporation. Azure DevOps is a trademark of Microsoft Corporation.

Users must have their own Azure DevOps account and appropriate licenses to use Azure DevOps services. This tool simply provides an interface to interact with Azure DevOps through the Model Context Protocol.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

🙏 Acknowledgments

• Built for use with Claude by Anthropic
• Powered by Azure DevOps and Azure CLI
• Implements the Model Context Protocol

📧 Support

For issues, questions, or suggestions, please open an issue on GitHub.

---

Made with ❤️ for the MCP community