zentao-mcp

⚠️ 本项目不再维护。 推荐改用禅道官方维护的 zentao-cli 和配套 Skills easysoft/zentao-skills：基于 RESTful API v2、内置 MCP server、模块覆盖更全，且持续更新。

已经在用本包的用户不受影响，可以继续装；新项目请优先选择上游：

npm i -g zentao-cli
npx skills add easysoft/zentao-skills

在命令行里查 Bug、任务、需求、待办、产品、项目、测试和文档，让你的 AI 助手也能直接操作禅道。

零依赖、单文件，装完即用。

快速开始

npx skills add leeguooooo/zentao-mcp -y -g

安装 CLI：

pnpm i -g @leeguoo/zentao-mcp

没有 pnpm？也可以用 npm：

npm i -g @leeguoo/zentao-mcp

不想装？直接跑：

npx -y @leeguoo/zentao-mcp --help

skills add 只负责安装 skill 文件；CLI 仍然建议全局安装后直接用 zentao 命令。

升级

zentao self-update --check   # 只看当前版本和最新版本，不改任何东西
zentao self-update           # 确认后用原来安装它的 npm / pnpm 升级（脚本里加 --yes）
zentao self-update --to 0.7.0 --yes   # 装指定版本

• 只读取 npm registry 的公开版本信息，再调用当初安装它的包管理器（npm i -g 或 pnpm add -g）。npx 运行、git 源码目录或识别不出来的安装方式不会被改动，只给出手动升级命令。
• 不登录禅道，不改 ~/.config/zentao/config.toml，不发版。升级后会核对版本并离线跑一次 --help，失败就装回原来的版本。
• --json 输出 current / target / result 等字段，方便脚本和 AI 助手读取。
• skill 文件要单独更新：重新执行 npx skills add leeguooooo/zentao-mcp -y -g（会覆盖你对 SKILL.md 的本地修改）。
• zentao release 是维护者发版用的，不是升级命令。
• 本包已停止新功能开发；self-update 只会升级本包，不会自动换成官方 zentao-cli。

登录

只需登录一次，凭据会保存到本地配置文件：

zentao login \
  --zentao-url=https://zentao.example.com/zentao \
  --zentao-account=你的账号 \
  --zentao-password=你的密码

注意： URL 通常需要包含 /zentao 路径。如果登录时看到 404，多半是少了这段。

验证登录状态：

zentao whoami

配置文件位置：~/.config/zentao/config.toml

支持的能力

当前 CLI 已支持这些对象和动作：

• 认证与连通性：login、whoami、self-test
• Bug：列表、查询、创建、指派、评论、解决、关闭、激活、查我的 Bug
• 任务：列表、查询、创建、开始、完成、暂停、关闭
• 需求：列表、查询、创建
• 待办：列表、查询、创建、完成、关闭
• 产品 / 项目 / 项目集 / 执行：列表，项目构建查询
• 计划 / 发布：列表、详情
• 测试用例 / 测试单 / 测试套件：列表、详情
• 文档库 / 文档：列表、详情
• 用户 / 部门：列表
• 问题 / 风险：列表、详情
• 机器可读输出：全部命令支持 --json

日常使用

查看产品列表

zentao products list

查看某个产品的 Bug

zentao bugs list --product 6

查看 Bug 详情

zentao bug get --id 1329

查看分配给我的 Bug

zentao bugs mine --status active

带详情：

zentao bugs mine --status active --include-details

需要原始 JSON？

任何命令后面加 --json：

zentao products list --json
zentao bugs list --product 6 --json
zentao bug get --id 1329 --json
zentao bugs mine --include-details --json

自检

验证 API 连接是否正常：

zentao self-test

命令总览

zentao login --zentao-url=... --zentao-account=... --zentao-password=...
zentao whoami
zentao self-test
zentao self-update --check

zentao products list
zentao programs list
zentao projects list
zentao projects builds --id 22
zentao executions list

zentao bugs list --product 6
zentao bugs mine --status active --include-details
zentao bug get --id 1329
zentao bug create --product 6 --title "bug title"
zentao bug assign --id 1329 --assigned-to someone
zentao bug resolve --id 1329 --resolution fixed
zentao bug close --id 1329
zentao bug activate --id 1329
zentao bug comment --id 1329 --comment "comment"

zentao tasks list --execution 25
zentao task get --id 388
zentao task create --execution 25 --name "task name"
zentao task start --id 388
zentao task finish --id 388
zentao task pause --id 388
zentao task close --id 388

zentao stories list --product 3
zentao story get --id 1
zentao story create --product 3 --title "story title"

zentao todos list
zentao todos get --id 1
zentao todos create --name "todo name"
zentao todos finish --id 1
zentao todos close --id 1

zentao plans list --product 3
zentao plans get --id 1
zentao releases list --product 3
zentao releases get --id 1

zentao testcases list --product 3
zentao testcases get --id 1
zentao testtasks list
zentao testtasks get --id 1
zentao testsuites list --product 3
zentao testsuites get --id 1

zentao docs libs
zentao docs list --lib 50
zentao docs get --id 1
zentao users list
zentao departments list
zentao issues list
zentao issues get --id 1
zentao risks list
zentao risks get --id 1

让 AI 帮你查禅道

只需对你的 AI 助手（Cursor / Claude Code / Windsurf 等）说：

帮我执行 npx skills add leeguooooo/zentao-mcp -y -g，然后帮我登录禅道

安装后你就可以直接说：

• "帮我看下产品 6 有哪些未解决的 Bug"
• "查一下 Bug #1329 的详情"
• "我名下还有多少活跃 Bug？"
• "帮我看执行 25 下有哪些任务"
• "查一下产品 3 的需求 / 计划 / 发布"
• "列出测试单、测试用例、测试套件"
• "看一下项目问题和风险"
• "打开文档库 50 里的文档列表"

当用户要求安装本仓库为 skill 时，请按顺序执行：

1. 安装 Skill

npx skills add leeguooooo/zentao-mcp -y -g

2. 安装 CLI

pnpm i -g @leeguoo/zentao-mcp || npm i -g @leeguoo/zentao-mcp

3. 验证安装

zentao --help

4. 引导登录

提示用户提供禅道 URL、账号和密码，然后执行：

zentao login --zentao-url="<用户的禅道URL>" --zentao-account="<账号>" --zentao-password="<密码>"

注意：URL 通常需要包含 /zentao，如 https://zentao.example.com/zentao

5. 验证

zentao whoami
zentao self-test

全部通过后告知用户安装完成。

常见问题

Q: 登录时报 404？ A: URL 需要包含 /zentao，比如 https://zentao.example.com/zentao，而不是 https://zentao.example.com/。

Q: 支持哪些禅道版本？ A: 支持禅道开源版和企业版的 REST API（v1）。

Q: 凭据安全吗？ A: 凭据以明文 TOML 存储在 ~/.config/zentao/config.toml，请确保文件权限安全。不要把配置文件提交到 Git。

链接

• npm
• GitHub
• 问题反馈