禅道 MCP Server

在 Kiro / Cursor / Claude Desktop 等支持 MCP 的 IDE 中直接查询和管理禅道 Bug、任务、项目、迭代，无需切换浏览器。

功能

Bug 管理

工具	说明
`get_my_bugs`	获取指派给我的 Bug 列表（支持分页、状态筛选）
`get_bug_detail`	获取指定 Bug 的详细信息
`resolve_bug`	解决 Bug（支持多种解决方案）
`close_bug`	关闭已解决的 Bug
`activate_bug`	重新激活已关闭/已解决的 Bug
`get_zentao_image`	下载禅道附件图片（如 bug.steps 中需要登录态 Token 才能拿到的 `<img src='…/file-read-<id>.png'>`），返回图片内容供 vision agent 直接识别

任务管理

工具	说明
`get_my_tasks`	获取指派给我的任务列表（分页、状态筛选）
`get_task_detail`	获取任务详情
`create_task`	在指定迭代下创建任务（支持 `parent` 创建子任务）
`update_task`	修改任务（标题/状态/指派/工时等）
`finish_task`	完成任务

项目与迭代

工具	说明
`get_projects`	获取项目列表（分页、状态筛选）
`get_project_detail`	获取项目详情
`get_executions`	获取迭代列表（可按项目过滤）
`get_execution_detail`	获取迭代详情
`create_execution`	新建迭代，自动继承项目团队成员

快速开始

1. 复制文件

将 mcp-zentao-server/ 整个文件夹复制到你的项目根目录（或任意位置）。

2. 安装依赖

cd mcp-zentao-server
npm install

3. 配置 MCP

根据你使用的 IDE，编辑对应的 MCP 配置文件：

Kiro: .kiro/settings/mcp.json（项目级）或 ~/.kiro/settings/mcp.json（全局）
Cursor: .cursor/mcp.json
Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）

填入以下内容（替换为你自己的账号密码）：

{
  "mcpServers": {
    "zentao": {
      "command": "node",
      "args": ["/你的绝对路径/mcp-zentao-server/index.js"],
      "env": {
        "ZENTAO_URL": "http://your-zentao-host:8081",
        "ZENTAO_ACCOUNT": "你的禅道账号",
        "ZENTAO_PASSWORD": "你的禅道密码"
      }
    }
  }
}

⚠️ args 中的路径必须是绝对路径，不支持相对路径。

凭据放到 `.env`（推荐，避免明文进 mcp.json）

把密码这类敏感值挪到脚本同目录的 .env，mcp.json 里只留 URL/账号：

cd mcp-zentao-server
cp .env.example .env
# 编辑 .env 填入真实密码
chmod 600 .env

# .env
ZENTAO_PASSWORD='你的禅道密码'

// mcp.json：去掉 ZENTAO_PASSWORD 行即可
"env": {
  "ZENTAO_URL": "http://your-zentao-host:8081",
  "ZENTAO_ACCOUNT": "你的禅道账号"
}

加载顺序：进程环境/mcp.json 优先，.env 兜底。.env 已被 .gitignore 忽略。

4. 重启 IDE / 重连 MCP

配置完成后重启 IDE 或在 MCP 面板中重连服务即可。

使用示例

在 AI 对话中直接用自然语言：

"看看我有哪些 Bug"
"查看 Bug #123 的详情"
"把 Bug #456 标记为已修复"
"我现在有哪些任务"
"在迭代 12 下创建一个任务，标题是 xxx，指派给 zhangsan"
"把任务 #888 标记完成，消耗 4 小时"
"列出所有进行中的项目"
"查看项目 5 下的迭代"

环境要求

Node.js >= 18（需要原生 fetch 支持）
禅道开源版 18.x（使用 REST API v1）
网络可访问禅道服务器（your-zentao-host:8081）

禅道 API 说明

基于禅道开源版 18.5 的 REST API v1：

Bug

接口	方法	说明
`/api.php/v1/tokens`	POST	登录认证
`/my-work-bug.json`	GET	我的 Bug
`/bug-view-{id}.json`	GET	Bug 详情
`/api.php/v1/bugs/:id`	PUT	解决 Bug
`/api.php/v1/bugs/:id/close`	POST	关闭 Bug
`/api.php/v1/bugs/:id/activate`	POST	激活 Bug

任务 / 项目 / 迭代

接口	方法	说明
`/my-work-task.json`	GET	我的任务
`/api.php/v1/tasks/:id`	GET	任务详情
`/api.php/v1/tasks/:id`	PUT	修改任务
`/api.php/v1/tasks/:id/finish`	POST	完成任务
`/api.php/v1/executions/:id/tasks`	POST	创建任务
`/api.php/v1/projects`	GET	项目列表
`/api.php/v1/projects/:id`	GET	项目详情
`/api.php/v1/projects/:id/executions`	GET	项目下迭代
`/api.php/v1/executions`	GET	迭代列表
`/api.php/v1/executions/:id`	GET	迭代详情
`/api.php/v1/projects/:id/executions`	POST	新建迭代
`/execution-manageMembers-:id.json`	POST	设置迭代团队（网页表单，需 cookie 会话）

常见问题

Q: 提示"登录失败" A: 检查 ZENTAO_ACCOUNT 和 ZENTAO_PASSWORD 是否正确，确认账号可以正常登录禅道网页版。

Q: 提示"请求失败 (401)" A: Token 过期，服务会自动重试。如果持续失败，重启 MCP 服务。

Q: 连接不上禅道服务器 A: 确认你在公司内网或 VPN 环境下，能 ping 通禅道服务器地址。