禅道 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_my_tasks |
获取指派给我的任务列表（分页、状态筛选） |
get_task_detail |
获取任务详情 |
create_task |
在指定迭代下创建任务（支持 parent 创建子任务） |
update_task |
修改任务（标题/状态/指派/工时等） |
finish_task |
完成任务 |
项目与迭代
| 工具 | 说明 |
|---|---|
get_projects |
获取项目列表（分页、状态筛选） |
get_project_detail |
获取项目详情 |
get_executions |
获取迭代列表（可按项目过滤） |
get_execution_detail |
获取迭代详情 |
快速开始
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中的路径必须是绝对路径，不支持相对路径。
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 | 迭代详情 |
常见问题
Q: 提示"登录失败"A: 检查 ZENTAO_ACCOUNT 和 ZENTAO_PASSWORD 是否正确，确认账号可以正常登录禅道网页版。
Q: 提示"请求失败 (401)"A: Token 过期，服务会自动重试。如果持续失败，重启 MCP 服务。
Q: 连接不上禅道服务器A: 确认你在公司内网或 VPN 环境下，能 ping 通禅道服务器地址。
