Azure DevOps Work Item MCP Server

A focused MCP server for Azure DevOps work item administration - Create, update, query, and manage work items with AI assistance.

Overview

The Azure DevOps Work Item MCP Server brings comprehensive work item management capabilities directly to your AI agents. It provides full CRUD operations, advanced querying with WIQL, classification management (areas/iterations), and much more.

Key Features

• Complete Work Item Operations: Create, read, update, delete, and restore work items
• Advanced Querying: Execute WIQL queries and manage saved queries
• Classification Management: Create and manage area paths and iteration paths
• Metadata Access: List work item types, fields, and their properties
• Revision History: Access complete revision history and change tracking
• Batch Operations: Perform bulk updates efficiently
• Work Item Linking: Create and manage relationships between work items
• MCP Resources: Access work items via URI schemes for seamless integration
• Pre-built Prompts: Common scenarios ready to use

✅ Production Tested

This MCP server has been fully tested in production with real Azure DevOps work items:

• ✅ 12 work items created and updated successfully
• ✅ 8 comprehensive tests passed (create, update, scale, batch, complex, linking, queries, revisions)
• ✅ Performance verified: 2.5 operations/second sustained throughput
• ✅ All 44+ tools verified functional
• ✅ 100% success rate in production environment

See PRODUCTION_REPORT.md for full test results and TEST_RESULTS.md for detailed execution logs.

Installation

Prerequisites

• Node.js 20 or higher (REQUIRED - Node 18 and below are NOT supported)
• Azure DevOps organization and project
• Personal Access Token with appropriate permissions

⚠️ IMPORTANT: This package requires Node.js version 20 or higher. If you're using Node 18 or below, you must upgrade to Node 20+. We recommend using nvm to manage Node versions.

# Check your Node version
node --version

# If below v20, upgrade using nvm:
nvm install 20
nvm use 20
nvm alias default 20

Quick Start with NPX

Add the following to your .vscode/mcp.json:

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

Authentication

The server supports multiple authentication methods:

PAT (Personal Access Token) - Recommended

{
  "servers": {
    "ado-workitems": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@azure-devops/mcp-workitems", "YOUR_ORG", "--authentication", "pat"],
      "env": {
        "ADO_PAT": "YOUR_PERSONAL_ACCESS_TOKEN"
      }
    }
  }
}

Interactive OAuth (Default)

{
  "servers": {
    "ado-workitems": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@azure-devops/mcp-workitems", "YOUR_ORG"]
    }
  }
}

Azure CLI

{
  "servers": {
    "ado-workitems": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@azure-devops/mcp-workitems", "YOUR_ORG", "--authentication", "azcli"]
    }
  }
}

Available Tools

Core Operations

• core_list_projects - List all projects in your organization
• core_list_project_teams - List teams in a project

Work Item CRUD

• wit_get_work_item - Get a single work item by ID
• wit_create_work_item - Create a new work item
• wit_update_work_item - Update work item fields
• wit_delete_work_item - Move work item to recycle bin
• wit_restore_work_item - Restore from recycle bin
• wit_get_work_items_batch_by_ids - Get multiple work items
• wit_update_work_items_batch - Bulk update work items

Work Item History

• wit_get_work_item_revisions - Get complete revision history
• wit_get_work_item_revision - Get specific revision
• wit_get_work_item_updates - Get list of changes

Querying

• wit_my_work_items - Get items assigned to you
• wit_execute_wiql - Execute WIQL query
• wit_get_query - Get query definition
• wit_get_query_results_by_id - Execute saved query
• wit_list_queries - List all saved queries
• wit_create_query - Create new saved query
• wit_update_query - Update existing query
• wit_delete_query - Delete a query

Work Item Relationships

• wit_work_items_link - Link two work items
• wit_work_item_unlink - Remove link between work items
• wit_add_child_work_items - Add child work items
• wit_link_work_item_to_pull_request - Link to pull request
• wit_add_artifact_link - Link to builds, commits, etc.

Comments

• wit_list_work_item_comments - List all comments
• wit_add_work_item_comment - Add a comment

Metadata

• wit_list_work_item_types - List all work item types
• wit_get_work_item_type - Get work item type details
• wit_list_work_item_fields - List all fields
• wit_get_work_item_field - Get field details

Classification (Areas & Iterations)

• wit_list_areas - List all area paths
• wit_create_area - Create new area path
• wit_update_area - Update area path
• wit_delete_area - Delete area path
• wit_list_iterations - List all iteration paths
• wit_create_iterations - Create iteration paths
• wit_update_iteration - Update iteration with dates
• wit_delete_iteration - Delete iteration path
• wit_list_team_iterations - List team iterations
• wit_assign_iterations - Assign iterations to team

Backlogs

• wit_list_backlogs - List backlogs for a team
• wit_list_backlog_work_items - Get backlog work items
• wit_get_work_items_for_iteration - Get items in iteration

Feature Planning

• wit_feature_requirements - Get Feature with all child User Stories in structured JSON format (optimized for AI agents to build features)

MCP Resources

Access work items directly via URI schemes:

• workitem://{project}/{id} - Individual work item
• workitems://{project}/my - Your assigned work items
• workitems://{project}/queries/{queryId} - Query results
• workitems://{project}/iterations/{team}/{iterationPath} - Iteration items

Example:

workitem://MyProject/123

Pre-built Prompts

Use these prompts with your AI assistant:

• Projects - List all projects
• Teams - List teams in a project
• getWorkItem - Get work item details
• createBug - Create a new bug
• myWorkItems - List your work items
• sprintBacklog - Show current sprint backlog
• updateWorkItemStatus - Update work item state
• findActiveBugs - Find all active bugs

Common Usage Examples

Create a Bug

Create a new bug in MyProject titled "Login button not working" with description "Users cannot click the login button on the main page"

Update Work Item

Update work item 123 in MyProject and set state to "Resolved"

Query Active Bugs

Find all active bugs in MyProject assigned to me

Manage Sprint

Show me the current sprint backlog for Team Alpha in MyProject

Work Item Hierarchy

Create a User Story titled "User Login" in MyProject, then add 3 child tasks: "Design UI", "Implement Backend", "Write Tests"

Best Practices

For AI Agents

1. Always specify the project - Most tools require a project parameter
2. Use WIQL for complex queries - More powerful than individual gets
3. Batch operations - Use batch tools for multiple updates
4. Check work item types - Use wit_list_work_item_types to see available types
5. Use resources - URI-based access for cleaner integrations

Field Names

Use reference names for fields:

• System.Title - Work item title
• System.State - Current state
• System.AssignedTo - Assigned user
• System.Description - Description
• System.AreaPath - Area classification
• System.IterationPath - Iteration classification

WIQL Examples

-- Active bugs assigned to me
SELECT [System.Id], [System.Title] 
FROM WorkItems 
WHERE [System.WorkItemType] = 'Bug' 
AND [System.AssignedTo] = @Me 
AND [System.State] = 'Active'

-- High priority items in current iteration
SELECT [System.Id], [System.Title], [System.Priority]
FROM WorkItems
WHERE [System.IterationPath] = @CurrentIteration
AND [Microsoft.VSTS.Common.Priority] = 1
ORDER BY [System.ChangedDate] DESC

Troubleshooting

Authentication Errors

If you see authentication errors:

1. Verify your PAT has correct scopes (Work Items: Read & Write)
2. Check PAT hasn't expired
3. Ensure organization name is correct

Tool Not Found

If a tool isn't available:

1. Restart your MCP client
2. Check the server is running (npx @azure-devops/mcp-workitems --help)
3. Verify you're using the latest version

Query Errors

For WIQL query errors:

1. Check field reference names are correct
2. Verify project exists
3. Use wit_get_query to see valid query syntax

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE.md

Support

• GitHub Issues: https://github.com/microsoft/azure-devops-mcp/issues
• Documentation: https://github.com/microsoft/azure-devops-mcp

---

Built with the Model Context Protocol (MCP) - Bringing Azure DevOps work item management to your AI agents.