禅道MCP

一、禅道MCP是什么？

禅道MCP是基于MCP模型上下文协议实现的桥接代理服务。可将禅道API2.0等遵循OpenAPI规范的REST接口，自动转为MCP标准工具，供Claude、Cursor、CodeBuddy等AI助手统一调用，实现跟禅道数据的相互调用（可以从禅道中获取数据，也可以更新禅道中的数据）。

适用版本：开源版21.7.8、企业版12.7、旗舰版7.7、IPD版4.7及以上版本。

本项目基于上游 openapi-mcp-server  修改扩展而来，采用MIT开源许可协议发布。

用户在保留原项目开源授权与版权规范的前提下，可自由使用、修改与分发。

二、核心特性

• 自动转换能力：从OpenAPI/Swagger文档自动生成MCP工具，无需人工编写适配逻辑，适配所有遵循该规范的REST API。

• 传输协议支持：同时兼容Streamable HTTP和SSE（Server-Sent Events），兼顾兼容（HTTP）和实时性（SSE），适配不同AI客户端的通信需求。

• 链路追踪：内置OpenTelemetry链路追踪和指标收集，能监控服务调用链路、收集运行指标，方便问题排查和服务优化。

• 多服务代理：单个禅道MCP实例可同时代理多个不同的API服务，不仅支持禅道API，还能适配其他遵循OpenAPI规范的系统API，扩展性强。

• 跨平台部署：支持Linux、macOS、Windows主流系统，部署灵活。

三、快速开始

（一）配置MCP服务（四选一即可）

1.Windows用户配置方式

1）下载包

2）解压包（以AMD-64位为例）

将下载的包解压到目录 D:\zentao-mcp 

3）修改MCP配置

复制配置模板：copy D:\zentao-mcp\config.example.yaml D:\zentao-mcp\config.yaml
修改配置文件：D:\zentao-mcp\config.yaml
schema_url: "D:/zentao-mcp/docs/zentao-openapi.json" # 更新为实际文件路径
base_url: "https://禅道域名/api.php/v2"               # 修改您的禅道访问域名 

4）启动MCP服务命令

在cmd命令行执行启动命令： D:\zentao-mcp\bin\zentao-mcp-windows-amd64.exe -config D:\zentao-mcp\config.yaml

2.Linux用户配置方式

1）下载包

AMD-64位：curl -k -L -O https://pkg.zentao.net/zentao-mcp/1.0.1/zentao-mcp-linux-amd64.tar.gz
ARM-64位：curl -k -L -O https://pkg.zentao.net/zentao-mcp/1.0.1/zentao-mcp-linux-arm64.tar.gz

2）解压包（以AMD-64位为例）

建目录：mkdir -p /opt/zentao-mcp
解压包：tar -zxvf zentao-mcp-linux-amd64.tar.gz -C /opt/zentao-mcp

3）修改MCP配置

复制配置模板：cp /opt/zentao-mcp/config.example.yaml /opt/zentao-mcp/config.yaml
修改配置文件：/opt/zentao-mcp/config.yaml
schema_url: "/opt/zentao-mcp/docs/zentao-openapi.json" # 更新为实际文件路径
base_url: "https://禅道域名/api.php/v2"                 # 修改您的禅道访问域名

4）启动MCP服务命令

/opt/zentao-mcp/bin/zentao-mcp-linux-amd64 -config /opt/zentao-mcp/config.yaml

3.Mac用户配置方式

1）下载包

AMD-64位：curl -k -L -O https://pkg.zentao.net/zentao-mcp/1.0.1/zentao-mcp-darwin-amd64.tar.gz
ARM-64位：curl -k -L -O https://pkg.zentao.net/zentao-mcp/1.0.1/zentao-mcp-darwin-arm64.tar.gz

2）解压包

建目录：mkdir /opt/zentao-mcp
解压包：tar -zxvf zentao-mcp-darwin-amd64.tar.gz -C /opt/zentao-mcp

3）修改MCP配置

复制配置模板：cp /opt/zentao-mcp/config.example.yaml /opt/zentao-mcp/config.yaml
修改配置文件：/opt/zentao-mcp/config.yaml
schema_url: "/opt/zentao-mcp/docs/zentao-openapi.json" # 更新为实际文件路径
base_url: "https://禅道域名/api.php/v2"                 # 修改您的禅道访问域名

4）启动MCP服务命令

/opt/zentao-mcp/bin/zentao-mcp-darwin-amd64 -config /opt/zentao-mcp/config.yaml

4.源代码启动（面向开发者）

1）克隆代码

git clone https://github.com/easysoft/zentao-mcp.git

2）启动项目

进入项目：cd zentao-mcp
下载依赖：go mod tidy
启动命令：go build -o zentao-mcp ./cmd/app（或使用task dev）

（二）配置MCP客户端（AI助手）

1.调用禅道API V2接口获取Token

curl -X POST "http://您的禅道域名/api.php/v2/users/login" \
   -H "Content-Type: application/json" \
   -d '{"account":"用户名","password":"密码"}' 

2.在AI助手中配置MCP（示例）

{
  "mcpServers": {
    "zentao": {
      "disabled": false,
      "type": "mcp",
      "url": "http://127.0.0.1:9090/zentao/mcp",
      "timeout": 60000,
      "headers": {
        "token": "禅道API V2 Token", # 禅道API V2要求header中必须传token
        "Authorization": ""
      }
    },
    "gitfox": {
      "disabled": false,
      "type": "sse",
      "url": "http://127.0.0.1:9090/gitfox/sse",
      "timeout": 60000,
      "headers": {
        "Authorization": "GitFox Token"
      }
    }
  }
}

3.在CodeBuddy配置禅道MCP服务后的效果：

四、场景示例

1.创建产品

▼通过CodeBuddy，在禅道中创建一个产品：

▼在禅道中查看产品是否创建成功：

2.创建需求

▼通过CodeBuddy，为禅道中的产品创建一个需求：

▼在禅道产品下确认需求是否产生：

3.创建代码库

▼通过CodeBuddy，根据禅道需求，在GitFox创建代码库：

▼在GitFox上确认是否有代码库生成：

4.生成代码并推送至仓库

▼通过CodeBuddy，在GitFox代码库生成一份脚手架代码：

▼在GitFox确认代码是否存在：

五、MCP客户端接入示例

1. VSCode

1.1 打开vscode对话框后，点上方设置按钮。

1.2 左侧选中 MCP Servers，点击右侧 Add Server，在弹窗 MCP 服务类型选择 HTTP。

1.3 基于上一步生成的配置，修改url（参考上述mcp服务端地址）、token（参考上述调用禅道API V2接口获取）字段。

1.4 在对话框发起 MCP 调用，完成服务请求。

2. Codex

2.1  在Codex中添加zentao mcp服务。

2.2 编辑~/.codex/config.toml 文件（执行上述命令后，会自动生成mcp_servers.zentao的配置区块），添加token（参考上述调用禅道API V2接口获取）后保存。

2.3 执行codex进入命令交互界面，输入/mcp 确认连通性。

2.4 在对话框发起 MCP 调用，完成服务请求。

3. Claude Code

3.1 在Claude Code中添加zentao mcp服务。

3.2 编辑~/.claude.json文件（执行上述命令后，会自动生成mcpServers的配置区块），添加token（参考上述调用禅道API V2接口获取）后保存。

3.3 执行claude进入命令交互界面，输入/mcp 确认连通性。

3.4 在对话框发起 MCP 调用，完成服务请求。

4. OpenCode

4.1  在OpenCode中添加zentao mcp服务。

4.2 在生成的配置信息中，补充token（参考上述调用禅道API V2接口获取）。

4.3 确认zentao mcp连通性。

5. Trea

5.1 打开Trea对话框后，点上方设置按钮。

5.2 左侧选中 MCP，点击右侧 Add Server，在弹窗 MCP 服务类型选择 HTTP。

5.3 编辑弹窗中mcp配置，填写url、token（参考上述调用禅道API V2接口获取）后点确定保存。

5.4 在对话框发起 MCP 调用，完成服务请求。

六、相关链接

• 禅道API手册

• GitFox介绍

• 项目源码