zentao-mcp

在命令行里查 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 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 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
• 问题反馈