Workitems DevOps

You deploy and run a Model Context Protocol MCP server that lets you interact with Azure DevOps Work Items directly from AI applications. It provides tools to query, filter, format, and update work items, including batch operations, item details, and state transitions, enabling seamless IA/LLM integration with your DevOps workflow.

How to use

You access the server through an MCP client and call the exposed tools to work with Azure DevOps work items. Start the local MCP server, then connect your IA/LLM workflow to it to perform tasks such as listing work items assigned to you, filtering by criteria or planned dates, retrieving full work item details with formatted output, updating states and planned dates, and adding comments. Use the provided tools to compose multi-step workflows and batch operations across multiple work items. You can also explore types and states, check allowed transitions, and extend the server with new tools as your needs evolve.

Key capabilities you will use include querying work items by ID, by custom criteria, or by planned dates; obtaining full details with formatted output; updating states, planned dates, and real effort; and adding comments. You can also list all work item types, fetch a type by name, view states for a type, and retrieve allowed transitions.

How to install

Prerequisites you need before running the MCP server:

• Python 3.13+

• Azure DevOps account with access to your project

• Personal Access Token (PAT) for Azure DevOps

Follow these steps to install and run the server locally:

# 1. Clone the project directory
git clone <your-repo>
cd workitems_devops_mcp

# 2. Install dependencies (example command shown in setup flow)
uv sync

Additional sections

Configuration and startup tips help you tailor the server to your environment and ensure secure operation.

Environment variables you should provide in your environment or a .env file:

• AZURE_DEVOPS_ACCESS_TOKEN — Your personal access token with appropriate permissions

• AZURE_DEVOPS_PROJECT — The Azure DevOps project name you are targeting

• AZURE_DEVOPS_ORGANIZATION — The Azure DevOps organization name

API and client details you may encounter:

• API Version: 7.0 (configurable in settings) and a User-Agent of workitems-devops-mcp/1.0

• Authentication is Basic with the PAT

How to run the server locally from your development environment:

# Run the MCP server directly
python server.py

# Alternative: run the main entry point
python main.py

Security and troubleshooting

Security tips to follow as you work with tokens and integration points.

• Do not commit tokens. Use environment variables instead.

• Use tokens with minimum required permissions for work item read/write operations

• Rotate tokens periodically and avoid logging sensitive information.

Common issues and fixes:

• Authentication errors: verify the PAT and environment values.

• Connection issues: confirm organization/project names and network access.

Examples of use cases

Example planning a daily query to fetch work items assigned to you and then retrieving details for visibility.

Example of updating a work item state and adding a progress comment to track changes.

Notes on extending functionality

You can add new tools by implementing a function in the business logic and exposing it as an MCP tool in the server entry point.

Output formatting can be customized in the formatter module to present results in an easily readable form.

Available tools

get_workitems_ids_assigned_to_user

Obtains IDs of work items assigned to the current user.

get_workitems_ids_assigned_to_user_by

Filters work items by custom criteria using WIQL-like expressions.

get_workitems_ids_assigned_to_user_by_planned_date

Filters work items by their planned start date.

get_workitems_details_by_ids

Retrieves full details for given work item IDs.

get_all_workitems_types

Lists all work item types available in the project.

get_workitem_type_by_name

Retrieves a specific work item type by name.

get_workitem_type_states

Lists states for a given work item type.

get_workitem_transitions_allowed

Gets allowed transitions for a type and state.

update_workitem_state

Updates the state of a single work item.

update_workitem_planned_date

Updates the planned start date of a work item.

update_workitem_real_effort

Updates the real effort spent on a work item.

update_workitem_description

Updates the description of a work item.

update_workitems_planned_date

Updates the planned start date for multiple work items.

add_workitem_comment

Adds a comment to a work item.