使用说明

Azure DevOps CLI MCP服务器

此MCP服务器封装Azure DevOps CLI命令，并将其作为AI代理的MCP工具公开。 此服务器专为Azure DevOps server（本地）部署而设计。

⚠️ Azure DevOps服务用户的重要通知：
如果你正在使用 Azure DevOps服务 （dev.ay.com），请改用官方的Microsoft azure DevOps MCP服务器：
https://github.com/microsoft/azure-devops-mcp

此服务器针对本地Azure DevOps server安装进行了优化。

主要特点

✅ Azure DevOps服务器 通过Azure CLI提供（本地）支持
✅ 自动CLI配置 -在启动时设置组织和项目默认值
✅ 跨平台 -适用于Windows、macOS和Linux
✅ 安全认证 -使用Azure CLI的标准PAT机制

先决条件

Node.js（v16+）
npm
带有DevOps扩展的Azure CLI： az extension add --name azure-devops

设置

安装先决条件：

# Install Azure CLI (if not already installed)
# Windows: https://aka.ms/installazurecliwindows
# macOS: brew install azure-cli
# Linux: https://docs.microsoft.com/en-us/cli/azure/install-azure-cli-linux

# Add Azure DevOps extension
az extension add --name azure-devops

克隆和构建：

git clone <repository-url>
cd ado-server-mcp
npm install
npm run build

配置MCP客户端：
- 将上面显示的配置添加到MCP客户端
- 将占位符值替换为实际的PAT和组织URL
- 重新启动MCP客户端以连接到服务器

运作原理

启动配置： 当服务器启动时，它会自动运行 az devops configure 将您的组织和项目设置为默认值
工具执行： MCP工具使用配置的默认值，因此您不需要指定 --organization 或 --project 在单个命令中
身份验证： 您的PAT通过环境变量安全地传递给Azure CLI

配置

环境变量

服务器要求在MCP客户端中配置这些环境变量：

变量	必填	描述	示例
`AZURE_DEVOPS_PAT`	✅ 是	用于身份验证的个人访问令牌	`your_pat_token_here`
`AZURE_DEVOPS_ORG`	✅ 是	组织或服务器URL	请参阅下面的示例
`AZURE_DEVOPS_PROJECT`	⚪ 可选	默认项目名称	`MyProject`

组织URL示例

Azure DevOps服务器（本地）：

https://devops.mycompany.com/DefaultCollection
https://tfs.mycompany.com:8080/tfs/DefaultCollection
https://ado-server.internal.company.com/DefaultCollection

注：虽然该服务器在技术上可以与Azure DevOps服务URL一起工作（例如。， https://dev.azure.com/yourorg)，我们建议使用官方微软Azure DevOps MCP服务器基于云的Azure DevOps服务。

MCP客户端配置

将此配置添加到您的MCP客户端（例如，VS Code的 mcp.json):

{
  "servers": {
    "ado-server-mcp": {
      "type": "stdio", 
      "command": "node",
      "args": ["z:/repos/ado-server-mcp/build/index.js"],
      "env": {
        "AZURE_DEVOPS_PAT": "your_pat_token_here",
        "AZURE_DEVOPS_ORG": "https://devops.mycompany.com/DefaultCollection",
        "AZURE_DEVOPS_PROJECT": "MyProject"
      }
    }
  }
}

注：这 AZURE_DEVOPS_PROJECT 参数是可选的，但建议使用。设置后，它将成为所有Azure CLI命令的默认项目，无需指定 --project 在单独的工具调用中。

可用工具

组织与项目管理

list_projects -使用az-cli列出Azure DevOps项目（使用配置的默认值）
project_show -显示特定项目的详细信息
teams_list -列出项目中的团队
team_show -显示特定团队的详细信息
team_members_list -列出团队成员

Azure板（工作项）

boards_query -使用WIQL（工作项查询语言）或现有查询ID/路径查询Azure Board工作项
boards_work_item_show -按ID显示特定工作项的详细信息
boards_work_item_create -创建新工作项
boards_work_item_update -更新现有工作项
boards_work_item_delete -删除工作项（移至回收站）
boards_area_list -列出项目的区域路径
boards_iteration_list -列出项目的迭代路径
boards_work_item_relation_types -列出组织中支持的工作项关系类型
boards_work_item_relation_add -向工作项添加关系

Azure管道

pipelines_list -列出项目中的管道
pipeline_show -显示特定管道的详细信息
pipelines_create -创建新管道
pipelines_run -运行管道
pipelines_update -更新管道
pipelines_delete -删除管道
pipelines_runs_list -列出管道运行
pipelines_runs_show -显示管道运行详细信息
pipelines_runs_tag_add -向管道管路添加标记
pipelines_runs_tag_delete -从管道管路中删除标记
pipelines_runs_tag_list -列出管道运行标记
pipelines_variable_create -创建管道变量
pipelines_variable_list -列出管道的变量
pipelines_variable_update -更新管道变量

Azure仓库

repos_list -列出项目中的存储库
repo_show -显示特定存储库的详细信息
repos_create -创建新存储库

Azure DevOps维基

wiki_list -列出项目中的Wiki
wiki_show -查看wiki详细信息
wiki_page_show -查看wiki页面
wiki_page_create -添加wiki页面

注：代码库中提供了用于工件、安全性、服务端点和横幅的其他工具，但目前已禁用。可以通过取消注释中的相关行来启用这些功能 src/tools/index.ts.

发展

构建: npm run build -将TypeScript编译为 build/
开始: npm run start -在stdio模式下运行MCP服务器
调试：检查MCP客户端日志是否存在连接问题

添加新工具

按照此模式 src/index.ts:

server.tool("tool_name", "Description", {}, async (args, extra): Promise<MCPToolResponse> => {
  const pat = process.env.AZURE_DEVOPS_PAT;
  
  if (!pat) {
    return {
      content: [{ type: "text", text: "AZURE_DEVOPS_PAT not set in environment" }],
      isError: true
    };
  }
  
  // Use configured defaults - no need to specify --organization or --project
  return await runAzCli(["devops", "your-command", "--output", "json"], pat);
});

要点：

✅ 始终验证PAT环境变量
✅ 使用 --output json 用于结构化响应
✅ 利用配置的默认值（无需 --organization 或 --project 旗帜）
✅ 返回正确 MCPToolResponse 带错误处理的格式

故障排除

常见问题

问题	原因	解决方案
“服务器在响应前退出”	stdout污染	使用 `dotenv@^16.x` 不 `@17.x`
“spawn az ENOENT”	找不到Azure CLI	确保Azure CLI已安装并位于PATH中
身份验证错误	无效的PAT或权限	验证PAT是否具有适当的Azure DevOps权限
“找不到组织”	组织URL错误	检查ADO类型的URL格式（服务与服务器）
“找不到项目”	项目名称无效	验证项目是否存在以及PAT是否有访问权限

调试提示

检查MCP客户端日志： 查找连接和工具执行错误
手动测试Azure CLI： 跑 az devops project list 验证CLI设置
验证环境变量： 确保PAT和组织URL正确
服务器配置： 检查Azure DevOps配置状态的启动日志

PAT权限

您的个人访问令牌需要以下作用域：

项目和团队： 读取（最小值）
工作项目： 阅读（如果使用工作项）
代码： 读取（如果使用存储库）
构建： 读取（如果使用管道）

安全

PAT令牌通过环境变量传递，从不记录
.env 文件被标记为gitignore，以防止意外提交
身份验证是通过Azure CLI的标准机制处理的

参考文献

微软官方Azure DevOps MCP服务器 - 推荐给Azure DevOps服务用户
MCP TypeScript SDK
MCP服务器概念
Azure DevOps CLI文档