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

Always specify the project - Most tools require a project parameter
Use WIQL for complex queries - More powerful than individual gets
Batch operations - Use batch tools for multiple updates
Check work item types - Use wit_list_work_item_types to see available types
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:

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

Tool Not Found

If a tool isn't available:

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

Query Errors

For WIQL query errors:

Check field reference names are correct
Verify project exists
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.

Azure DevOps Work Item MCP Server