Skip to main content
Glama
Sign In
Zentao Bug MCP

Zentao Bug MCP

by ceeyang
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

禅道 MCP

让 Cursor / Claude / Windsurf 等 AI 直接读写禅道的 Bug / 需求(story) / 任务(task)。

适配禅道开源版 16.5+ / 18.12 · REST API v1

30 秒：能干什么

你想…

在 AI 里这样说

确认装好了

「调用 zentao_health_check 检查禅道连接」

看我负责的 Bug

「列出指派给我的 Bug，最新的 10 条」

读重现步骤修 Bug

「读取 Bug #12345 详情，按 steps 帮我改代码」

查某产品下的需求

「列出产品 3 下未关闭的需求」

提一个需求

「在产品 3 下建需求：标题 xxx，描述 yyy」（需开写权限）

拆任务 / 报工

「在迭代 5 下给 alice 建开发任务，预计 4 小时」「把任务 #88 标完成，消耗 3 小时」

修完回写禅道

「dryRun 预演把 #12345 标为 fixed，备注 xxx」（需开写权限）

安装方式一：npm（推荐）

在 AI 客户端的 MCP 配置里直接用 npx，无需 clone、无需构建：

{
  "mcpServers": {
    "zentao": {
      "command": "npx",
      "args": ["-y", "@ceeyang/zentao-mcp"],
      "env": {
        "ZENTAO_URL": "https://your-zentao-host",
        "ZENTAO_ACCOUNT": "your_account",
        "ZENTAO_PASSWORD": "your_password"
      }
    }
  }
}

也可以全局装：npm i -g @ceeyang/zentao-mcp，然后把 command 换成 zentao-mcp、args 留空。

安装方式二：一条命令脚本安装

curl -fsSL https://raw.githubusercontent.com/ceeyang/zentao_mcp/main/install.sh | bash

Windows：irm https://raw.githubusercontent.com/ceeyang/zentao_mcp/main/install.ps1 | iex

会自动下载、构建，并写入检测到的 18 种 AI 客户端配置。

装完 重启 AI 客户端，按上表开聊即可。更多示例 → docs/FEATURES.zh-CN.md

Related MCP server: zentao-mcp-server

已实现功能

安装与集成

  • 一条命令从 GitHub 下载、构建、写入 MCP 配置（~/.local/share/zentao-mcp）

  • 交互安装：现场输入禅道账号，或选「稍后配置」

  • 18 种 AI 客户端：Cursor、Claude Desktop、Claude Code、Windsurf、Trae、VS Code、Cline、OpenCode、Continue、Zed 等（INSTALL_PLATFORMS=auto 自动检测）

  • node 绝对路径，避免 Cursor spawn ENOENT

读 Bug（默认开启）

工具

能力

zentao_list_my_bugs

指派给当前账号的 Bug（不用记产品 ID）

zentao_list_bugs

按产品 / 项目 / 执行筛选

zentao_get_bug

详情 + HTML 重现步骤转纯文本（stepsPlain）

zentao_health_check

连通性 + 写权限开关状态

写 Bug（默认关闭，防误操作）

工具

需环境变量

zentao_resolve_bug

ZENTAO_ALLOW_RESOLVE_BUG=true

zentao_close_bug

ZENTAO_ALLOW_CLOSE_BUG=true

zentao_activate_bug

ZENTAO_ALLOW_ACTIVATE_BUG=true

均支持 dryRun: true 先预演。详见 功能示例。

需求 story / 任务 task

先用 zentao_list_scopes 找 ID：建需求要产品 ID，建任务要迭代(execution) ID。

工具

能力

需环境变量

zentao_list_scopes

列产品 / 项目 / 迭代，拿 ID

只读

zentao_list_stories

按产品 / 项目 / 迭代列需求

只读

zentao_get_story

详情 + 描述/验收标准转纯文本、关联任务与 Bug

只读

zentao_create_story

提需求

ZENTAO_ALLOW_WRITE_STORY=true

zentao_update_story

改标题 / 优先级 / 分类 / 模块等

同上

zentao_change_story

改描述 / 验收标准（禅道单独版本化，会升版本号）

同上

zentao_close_story / zentao_assign_story

关闭 / 指派

同上

zentao_list_tasks

列迭代下任务；不传 executionId 就是「我的任务」

只读

zentao_get_task

详情 + 描述纯文本 + 操作历史

只读

zentao_create_task

拆任务

ZENTAO_ALLOW_WRITE_TASK=true

zentao_update_task

改字段

同上

zentao_start_task / zentao_finish_task

开始 / 完成（报工）

同上

zentao_close_task / zentao_assign_task

关闭 / 指派

同上

写操作同样支持 dryRun: true。

改需求描述请用 zentao_change_story——禅道把 spec/verify 和其它字段分开版本化， 普通更新接口不会改描述。另外 18.x 的 PUT /stories/:id 在需求没有评审人时会被禅道拒绝， 此时工具会返回 REVIEWER_REQUIRED 并提示补 reviewer。

安全与运维

  • 产品白名单 ZENTAO_ALLOWED_PRODUCTS

  • 自签名 HTTPS ZENTAO_SKIP_SSL

  • Token / 账号密码双模式，401 自动刷新

  • 统一 JSON 响应信封，方便 AI 解析

尚未实现

  • Bug 指派推送、群 每日汇总 机器人（需另建服务，见 讨论方向）

  • 需求评审流程（review / submitreview）、任务批量创建

对话示例

Morning standup：

你：我禅道上有哪些没关的 Bug？
AI：→ zentao_list_my_bugs → 返回 6 条列表

你：重点看 #12345，读步骤，在 src/auth 里找原因
AI：→ zentao_get_bug → 读 stepsPlain → 改代码

修完回写（已开 ZENTAO_ALLOW_RESOLVE_BUG）：

你：测试过了，把 #12345 标为 fixed，备注「修复 token 过期未刷新」
AI：→ zentao_resolve_bug(resolution=fixed, comment=...)

安装说明

  1. 执行上方 curl | bash（或 PowerShell irm ... | iex）

  2. 按提示填禅道地址 / 账号 / 密码（可跳过）

  3. 选 AI 平台（直接回车 = auto 自动检测）

  4. 完全重启 Cursor / Claude 等

  5. 对话：调用 zentao_health_check 检查连接

稍后配置账号 — 编辑 ~/.cursor/mcp.json 等里的 zentao.env：

"env": {
  "ZENTAO_URL": "https://your-zentao-host",
  "ZENTAO_ACCOUNT": "your_account",
  "ZENTAO_PASSWORD": "your_password",
  "ZENTAO_SKIP_SSL": "true"
}

完整安装文档 · 发给同事

文档

文档

内容

FEATURES.zh-CN.md

功能清单 + 每个工具的 AI 说法示例

INSTALL.zh-CN.md

安装、平台列表、FAQ

SHARE.md

复制给同事的一键安装文案

DEV-DOCKER.zh-CN.md

本地 Docker 禅道：起测试环境 + 跑端到端测试

环境变量（摘要）

变量

说明

ZENTAO_URL / ZENTAO_ACCOUNT / ZENTAO_PASSWORD

禅道凭据

ZENTAO_SKIP_SSL

自签名证书 → true

ZENTAO_ALLOW_RESOLVE_BUG / _CLOSE_BUG / _ACTIVATE_BUG

Bug 写操作开关，默认 false

ZENTAO_ALLOW_WRITE_STORY / ZENTAO_ALLOW_WRITE_TASK

需求 / 任务写操作开关，默认 false

ZENTAO_ALLOWED_PRODUCTS

可选，产品 ID 白名单

INSTALL_PLATFORMS

安装时：auto / all / cursor,claude

完整列表：.env.example

维护者

git clone https://github.com/ceeyang/zentao_mcp.git
cd zentao_mcp && npm install && npm run build && ./install.sh
npm run test:install     # 安装脚本 E2E
npm run test:story-task  # 需求/任务 E2E（需本地禅道，见 docs/DEV-DOCKER.zh-CN.md）
npm run verify:github    # 检查 raw 安装链
npm run pack:release     # 离线 tgz
npm publish              # 发布到 npm（@ceeyang/zentao-mcp）

License

MIT

Available Tools

7 tools
zentao_activate_bugA

Re-activate a bug when fix verification fails. Requires ZENTAO_ALLOW_ACTIVATE_BUG=true unless dryRun=true.

Inputs: bugId (required), dryRun, comment, assignedTo, +1 more.

zentao_close_bugA

Close a bug. Requires ZENTAO_ALLOW_CLOSE_BUG=true unless dryRun=true.

Inputs: bugId (required), dryRun, comment.

zentao_get_bugA

Get a single bug with raw payload and AI-friendly summary including plain-text steps.

Inputs: bugId (required).

zentao_health_checkC

Check ZenTao MCP configuration, authentication, and write-operation gates.

Inputs: forceTokenRefresh.

zentao_list_bugsB

List bugs by product, project, or execution scope.

Inputs: id (required), scope (required), page, limit, +4 more.

zentao_list_my_bugsA

List bugs assigned to the current logged-in user. No product/project ID required.

Inputs: page, type, limit, order.

zentao_resolve_bugB

Resolve a bug after fixing code. Requires ZENTAO_ALLOW_RESOLVE_BUG=true unless dryRun=true.

Inputs: bugId (required), resolution (required), dryRun, comment, +3 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.7/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool has a unique action and target: activate, close, get, health check, list (general), list (my), resolve. No two tools overlap in purpose; an agent can clearly distinguish them.

    Naming Consistency5/5

    All tools use a consistent 'zentao_verb_noun' snake_case pattern (e.g., zentao_activate_bug, zentao_list_bugs). Even zentao_health_check follows the pattern, and zentao_list_my_bugs is a natural variation. No mixing of styles.

    Tool Count5/5

    With 7 tools covering core bug operations and a health check, the number is well-scoped for a bug management MCP server. It is neither too sparse nor too bloated.

    Completeness4/5

    The set covers the main bug lifecycle states (activate, resolve, close) plus listing and retrieval. However, it lacks create and update operations, which are typical for a bug tracker. This is a minor gap that agents can work around if bugs are created via other means.

    Maintenance

    ActivityStale
    ResponsivenessLimited data

    Resources

    Related MCP Connectors

    Related MCP Servers