Azure MCP FastMCP Server

A Model Context Protocol (MCP) server that provides Azure DevOps integration through a set of tools for managing projects, work items, teams.

Table of Contents

• Azure MCP FastMCP Server
  • Table of Contents
  • 🚀 Features
  • 📦 Installation
    • Using npx (Recommended)
    • Local Development
  • 🔧 Configuration
    • Environment Variables
    • Setting Environment Variables
      • Method 1: Direct Environment Variables
      • Method 2: Using .env File
      • Method 3: System Environment Variables
  • 🛠️ Available Tools
  • 🔐 Azure DevOps Permissions
  • 🚀 Usage Examples
    • Basic Usage
    • With MCP Client Configuration
    • Bulk Create Work Items
    • Assign Work Item to Iteration
  • 🛠️ Development
    • Prerequisites
    • Development Commands
    • Project Structure
  • 📄 License
  • 🤝 Contributing
  • 📞 Support
  • ⚠️ Known Issues

🚀 Features

• Standalone Executable: No dependencies required when using npx
• Azure DevOps Integration: Full access to Azure DevOps REST API
• MCP Protocol: Compatible with any MCP client
• Multiple Tools: Projects, Work Items, Teams, and Policies management

📦 Installation

Using npx (Recommended)

# No installation required - runs directly
npx -y @ahmedrowaihi/azure-mcp-fastmcp

Local Development

# Clone the repository
git clone https://github.com/ahmedrowaihi/azure-mcp-fastmcp.git
cd azure-mcp-fastmcp

# Install dependencies
bun install

# Build the project
bun run build

# Run the built server
bun run dist/main.js

🔧 Configuration

Environment Variables

The server requires the following environment variables:

# Required: Your Azure DevOps organization URL
AZURE_ORG_URL=https://dev.azure.com/yourorg

# Required: Your Azure DevOps Personal Access Token (PAT)
AZURE_PERSONAL_ACCESS_TOKEN=your_pat_here

Setting Environment Variables

Method 1: Direct Environment Variables

AZURE_ORG_URL=https://dev.azure.com/yourorg \
AZURE_PERSONAL_ACCESS_TOKEN=your_token \
npx -y @ahmedrowaihi/azure-mcp-fastmcp

Method 2: Using .env File

Create a .env file in your project root:

AZURE_ORG_URL=https://dev.azure.com/yourorg
AZURE_PERSONAL_ACCESS_TOKEN=your_token

Then run:

npx dotenv -e .env -- npx -y @ahmedrowaihi/azure-mcp-fastmcp

Method 3: System Environment Variables

Add to your shell profile (~/.bashrc, ~/.zshrc, etc.):

export AZURE_ORG_URL="https://dev.azure.com/yourorg"
export AZURE_PERSONAL_ACCESS_TOKEN="your_token"

🛠️ Available Tools

• Tools

🔐 Azure DevOps Permissions

Your Personal Access Token (PAT) needs the following permissions:

• Code: Read (for repository access)
• Work Items: Read & Write (for work item management)
• Project and Team: Read (for project and team information)
• Policy: Read (for branch policy access)

🚀 Usage Examples

Basic Usage

# Start the MCP server
npx -y @ahmedrowaihi/azure-mcp-fastmcp

With MCP Client Configuration

If using an MCP client like Claude Desktop, add to your configuration:

{
  "mcpServers": {
    "azure-devops": {
      "command": "npx",
      "args": ["-y", "@ahmedrowaihi/azure-mcp-fastmcp"],
      "env": {
        "AZURE_ORG_URL": "https://dev.azure.com/yourorg",
        "AZURE_PERSONAL_ACCESS_TOKEN": "your_token"
      }
    }
  }
}

Bulk Create Work Items

{
  "project": "MyProject",
  "items": [
    {
      "type": "Epic",
      "title": "Epic 1",
      "children": [
        {
          "type": "Feature",
          "title": "Feature A",
          "children": [
            {
              "type": "User Story",
              "title": "Story 1",
              "children": [
                { "type": "Task", "title": "Task X" },
                { "type": "Task", "title": "Task Y" }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Assign Work Item to Iteration

{
  "id": 12345,
  "iterationId": "MyProject\\Iteration 1"
}

🛠️ Development

Prerequisites

• Bun (JavaScript runtime)
• Node.js 18+ (for compatibility)

Development Commands

# Install dependencies
bun install

# Build the project
bun run build

# Start development server
bun run dev

# Run the built server
bun run dist/main.js

Project Structure

├── azure/           # Azure DevOps services and connection
├── formatters/      # Data formatting utilities
├── mcp/            # MCP server and tools
├── dist/           # Built executable (generated)
├── main.ts         # Entry point
└── package.json    # Project configuration

📄 License

This project is licensed under the MIT License.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📞 Support

If you encounter any issues or have questions, please open an issue on GitHub.

---

Note: This MCP server is designed to be a standalone executable that doesn't require installing dependencies when used with npx. All dependencies are bundled into the final executable for optimal user experience.

---

⚠️ Known Issues

• Iteration Node Update Limitation: Updating project-level iteration node dates (start/end) via the Azure DevOps SDK fails with "Iteration node not found" even when the node is confirmed to exist and is fetchable by ID. All tested path formats fail for update/fetch by path, but fetching by ID works. This may be an SDK bug, REST/SOAP mismatch, or permissions issue. If you encounter this, consider using the Azure DevOps REST API directly or check for updates to the SDK.