禅道 MCP

让 Cursor / Claude / Windsurf 等 AI 直接读写禅道的 Bug / 需求(story) / 任务(task)。

适配禅道开源版 16.5+ / 18.12 · REST API v1

---

30 秒：能干什么

安装方式一：npm（推荐）

在 AI 客户端的 MCP 配置里直接用 npx，无需 clone、无需构建：

{
  "mcpServers": {
    "zentao": {
      "command": "npx",
      "args": ["-y", "@ceeyang/zentao-mcp"],
      "env": {
        "ZENTAO_URL": "https://your-zentao-host",
        "ZENTAO_ACCOUNT": "your_account",
        "ZENTAO_PASSWORD": "your_password"
      }
    }
  }
}

也可以全局装：npm i -g @ceeyang/zentao-mcp，然后把 command 换成 zentao-mcp、args 留空。

安装方式二：一条命令脚本安装

curl -fsSL https://raw.githubusercontent.com/ceeyang/zentao_mcp/main/install.sh | bash

Windows：irm https://raw.githubusercontent.com/ceeyang/zentao_mcp/main/install.ps1 | iex

会自动下载、构建，并写入检测到的 18 种 AI 客户端配置。

装完 重启 AI 客户端，按上表开聊即可。更多示例 → docs/FEATURES.zh-CN.md

---

已实现功能

安装与集成

• 一条命令从 GitHub 下载、构建、写入 MCP 配置（~/.local/share/zentao-mcp）
• 交互安装：现场输入禅道账号，或选「稍后配置」
• 18 种 AI 客户端：Cursor、Claude Desktop、Claude Code、Windsurf、Trae、VS Code、Cline、OpenCode、Continue、Zed 等（INSTALL_PLATFORMS=auto 自动检测）
• node 绝对路径，避免 Cursor spawn ENOENT

读 Bug（默认开启）

写 Bug（默认关闭，防误操作）

均支持 dryRun: true 先预演。详见 功能示例。

需求 story / 任务 task

先用 zentao_list_scopes 找 ID：建需求要产品 ID，建任务要迭代(execution) ID。

写操作同样支持 dryRun: true。

改需求描述请用 zentao_change_story——禅道把 spec/verify 和其它字段分开版本化， 普通更新接口不会改描述。另外 18.x 的 PUT /stories/:id 在需求没有评审人时会被禅道拒绝， 此时工具会返回 REVIEWER_REQUIRED 并提示补 reviewer。

安全与运维

• 产品白名单 ZENTAO_ALLOWED_PRODUCTS
• 自签名 HTTPS ZENTAO_SKIP_SSL
• Token / 账号密码双模式，401 自动刷新
• 统一 JSON 响应信封，方便 AI 解析

尚未实现

• Bug 指派推送、群 每日汇总 机器人（需另建服务，见 讨论方向）
• 需求评审流程（review / submitreview）、任务批量创建

---

对话示例

Morning standup：

你：我禅道上有哪些没关的 Bug？
AI：→ zentao_list_my_bugs → 返回 6 条列表

你：重点看 #12345，读步骤，在 src/auth 里找原因
AI：→ zentao_get_bug → 读 stepsPlain → 改代码

修完回写（已开 ZENTAO_ALLOW_RESOLVE_BUG）：

你：测试过了，把 #12345 标为 fixed，备注「修复 token 过期未刷新」
AI：→ zentao_resolve_bug(resolution=fixed, comment=...)

---

安装说明

1. 执行上方 curl | bash（或 PowerShell irm ... | iex）
2. 按提示填禅道地址 / 账号 / 密码（可跳过）
3. 选 AI 平台（直接回车 = auto 自动检测）
4. 完全重启 Cursor / Claude 等
5. 对话：调用 zentao_health_check 检查连接

稍后配置账号 — 编辑 ~/.cursor/mcp.json 等里的 zentao.env：

"env": {
  "ZENTAO_URL": "https://your-zentao-host",
  "ZENTAO_ACCOUNT": "your_account",
  "ZENTAO_PASSWORD": "your_password",
  "ZENTAO_SKIP_SSL": "true"
}

完整安装文档 · 发给同事

---

文档

---

环境变量（摘要）

完整列表：.env.example

---

维护者

git clone https://github.com/ceeyang/zentao_mcp.git
cd zentao_mcp && npm install && npm run build && ./install.sh
npm run test:install     # 安装脚本 E2E
npm run test:story-task  # 需求/任务 E2E（需本地禅道，见 docs/DEV-DOCKER.zh-CN.md）
npm run verify:github    # 检查 raw 安装链
npm run pack:release     # 离线 tgz
npm publish              # 发布到 npm（@ceeyang/zentao-mcp）

License

MIT