chandao-mcp

禅道（ZenTao）MCP Server —— 让 Cursor、Claude 等 AI 助手直接读写你的禅道：查任务、创建任务（富文本 / 内嵌图片 / 附件）、读需求、下载附件、开始 / 完成任务、查询和处理 Bug。

基于禅道 REST API v1（/api.php/v1）与网页表单接口，通过 stdio 与 MCP 客户端通信。

功能特性

• 任务详情聚合：一次调用拿到任务描述、关联需求与验收标准、评论、附件、内嵌图片与外链
• 创建任务：在指定执行下创建任务，支持 HTML 富文本、内嵌图片、附件上传
• mustRead 清单：自动提取需求中的图片 / 附件 / 外链并列成清单——任务的真实需求经常写在图片和附件里，提醒 AI 逐一读完再动手
• 附件直接下载：用 API Token 直连禅道文件路由，图片下载到本地后可直接交给多模态模型查看
• 完整任务流：创建任务 → 查列表 → 读详情 → 开始任务 → 完成任务（支持工时、指派、备注）
• Bug 处理：按产品 / 状态筛选、查看详情、提交解决、重新激活

快速开始

在 MCP 客户端配置中添加（以 Cursor 的 mcp.json 为例）：

{
  "mcpServers": {
    "chandao": {
      "command": "npx",
      "args": ["-y", "chandao-mcp"],
      "env": {
        "ZENTAO_BASE_URL": "https://your-zentao.example.com/api.php/v1",
        "ZENTAO_ACCOUNT": "your-account",
        "ZENTAO_TOKEN": "your-api-token"
      }
    }
  }
}

要求 Node.js ≥ 20。

环境变量

| 变量 | 必填 | 说明 | | --- | --- | --- | | ZENTAO_BASE_URL | 是* | 禅道 API 地址，形如 https://xxx/api.php/v1 | | ZENTAO_ACCOUNT | 是* | 禅道账号 | | ZENTAO_TOKEN | 二选一* | API Token（推荐，在禅道「个人设置 → 密钥」创建） | | ZENTAO_PASSWORD | 二选一* | 账号密码 | | ZENTAO_HTTP_BACKEND | 否 | axios / curl，非 Windows 默认 curl | | LOG_LEVEL | 否 | fatal / error / warn / info / debug / trace，默认 info | | REQUEST_TIMEOUT_MS | 否 | 请求超时毫秒数，默认 10000 | | RETRY_COUNT | 否 | 失败重试次数 0–5，默认 2 |

* 未配置时服务也能启动，之后在会话中用 initZentao 工具登录即可。

工具列表

会话

| 工具 | 功能 | | --- | --- | | initZentao | 初始化禅道连接并登录（支持密码或 Token） | | healthCheck | 检查当前会话与服务可用性 |

任务

| 工具 | 功能 | | --- | --- | | createTask | 在指定执行 / 迭代下创建任务；支持富文本描述、内嵌图片（imagePaths）、附件（attachmentPaths） | | getMyTasks | 按状态 / 执行（迭代）筛选我的任务列表，默认只看未完成（wait + doing + pause） | | getTaskDetail | 查看任务详情：任务描述、关联需求的描述与验收标准、附件、内嵌图片、外链、评论，并生成开发前必读的 mustRead 清单 | | downloadTaskFile | 下载禅道中的图片 / 附件到本地并返回保存路径，支持文件 URL 或文件 ID 两种方式 | | startTask | 开始任务（进入 doing 状态），可填已消耗 / 剩余工时 | | finishTask | 完成任务（进入 done 状态），可填本次工时、完成备注（建议附 MR 链接）、完成后指派人 |

产品与 Bug

| 工具 | 功能 | | --- | --- | | getProducts | 获取产品列表 | | getMyBugs | 按状态与产品筛选我的 Bug 列表 | | getBugDetail | 查看单个 Bug 详情 | | resolveBug | 提交 Bug 解决动作（fixed / notrepro / duplicate 等） | | activateBug | 激活（重新打开）已解决 / 已关闭的 Bug |

典型工作流

创建任务

1. 准备本地图片 / 附件（可选）
2. createTask 指定 executionId、name，可传 desc/descHtml、imagePaths、attachmentPaths
3. 用返回的 url / id 在禅道页面核对

开发闭环

1. getMyTasks 查看待办任务
2. getTaskDetail 读取任务详情，拿到 mustRead 清单
3. downloadTaskFile 逐一下载清单中的图片 / 附件，读完再动手
4. startTask 将任务置为进行中
5. 开发、提交代码、创建 MR
6. finishTask 填写工时、附上 MR 链接并完成任务

更新说明

详见 CHANGELOG.md。

1.1.0（2026-08-05）

• 新增 createTask：创建任务，支持富文本、内嵌图片、附件
• 修复 getTaskDetail 对禅道 files 对象格式的解析

License

ISC