Skip to main content
Glama

ZenTao MCP Server (API V1.0)

基于 TypeScript + Node.js + @modelcontextprotocol/sdk 的禅道 MCP 服务,支持:

  • 登录初始化(initZentao)

  • 查看产品(getProducts)

  • 查看我的 bug(getMyBugs)

  • 查看 bug 详情(getBugDetail)

  • 解决 bug(resolveBug)

  • 激活 bug(activateBug,重新打开)

1. 环境准备

npm install
cp .env.example .env

请在 .env 中配置禅道地址与鉴权信息(推荐在运行时通过 initZentao 传入账号密码,不在文件中存明文)。

Related MCP server: ZenTao MCP Server

2. 从 npm / npx 运行(其它机器推荐)

npm 包名:@wudidada/zentao-mcp-server(作用域包;可执行命令 zentao-mcp-server)。

要求:Node.js >= 20。Linux/macOS 建议安装系统 curl(默认 HTTP 后端为 curl)。

2.1 命令行试跑

npx -y @wudidada/zentao-mcp-server

HTTP 模式示例:

MCP_TRANSPORT=http npx -y @wudidada/zentao-mcp-server

2.2 Cursor mcp.json(stdio + 环境变量)

在项目或用户目录下的 .cursor/mcp.json 中配置,例如:

{
  "mcpServers": {
    "zentao": {
      "command": "npx",
      "args": ["-y", "@wudidada/zentao-mcp-server"],
      "env": {
        "ZENTAO_BASE_URL": "http://your-host/zentao/api.php/v1",
        "ZENTAO_ACCOUNT": "your_account",
        "ZENTAO_PASSWORD": "your_password",
        "ZENTAO_HTTP_BACKEND": "curl",
        "LOG_LEVEL": "info"
      }
    }
  }
}

修改配置后请完全重启 Cursor。也可将 args 中的包名改为固定版本,例如 @wudidada/zentao-mcp-server@1.0.1。

2.3 维护者:发布到 npm

npm run build
npm test
npm publish --access public

首次发布前需 npm login,并确保 package.json 中 version 未被占用。

源码仓库:https://github.com/wudidada/zentao-mcp-server

3. 启动方式

stdio(本地 IDE 首选)

npm run start:stdio

HTTP/SSE(远程接入)

npm run start:http

默认端口 3000,健康检查:

curl http://localhost:3000/healthz

4. 构建与测试

npm run build
npm test

5. MCP 工具参数说明

initZentao

  • baseUrl?: string

  • account?: string

  • password?: string

  • token?: string

参数为空时自动回退读取 ZENTAO_BASE_URL、ZENTAO_ACCOUNT 以及 ZENTAO_PASSWORD/ZENTAO_TOKEN。显式传参时 password 与 token 二选一。

getMyBugs

  • status?: "active" | "resolved" | "closed" | "all"(默认 active)

  • productId?: number

getBugDetail

  • bugId: number

activateBug

  • bugId: number

  • assignedTo?: string(指派给,账号)

  • openedBuild?: string | string[](影响版本,文档为数组;不传则默认 ["trunk"])

  • comment?: string

resolveBug

  • bugId: number

  • resolution.resolution: "fixed" | "notrepro" | "duplicate" | "bydesign" | "willnotfix" | "tostory" | "external"

  • resolution.resolvedBuild?: string(当解决方案为 fixed 时,服务端固定提交 trunk,忽略该字段,避免部分禅道网页端显示异常)

  • resolution.duplicateBug?: number(当 resolution=duplicate 时必填)

  • resolution.comment?: string

6. 安全与运维基线

  • 日志默认对 password/token/authorization 做脱敏处理

  • 默认请求超时 10s

  • 查询接口(GET)支持指数退避重试

  • HTTP 模式提供 /healthz 健康检查

  • 若配置了 ZENTAO_BASE_URL + ZENTAO_ACCOUNT +(ZENTAO_PASSWORD 或 ZENTAO_TOKEN),进程启动时会自动登录,无需每次先调 initZentao

  • 会话缺失或接口返回 401 时,会使用内存中缓存的登录配置自动续登一次;并发请求共享同一次续登

  • 启动阶段自动登录失败不会阻止 MCP 服务启动,首次业务调用会再次尝试登录

  • ZENTAO_HTTP_BACKEND:axios 使用 Node 内置 HTTP;curl 调用系统 curl。在非 Windows 上默认 curl,用于规避部分禅道实例对「Node 客户端 + Token 头 + GET」长时间无响应的问题

6.1 环境变量一览

变量

说明

ZENTAO_BASE_URL

禅道 API V1 根地址,如 http://host/zentao/api.php/v1

ZENTAO_ACCOUNT / ZENTAO_PASSWORD / ZENTAO_TOKEN

自动登录用(密码与 token 二选一)

ZENTAO_HTTP_BACKEND

axios 或 curl;未设置时 Linux/macOS 默认 curl,Windows 默认 axios

7. 项目结构

src/
  adapters/      # 禅道 API V1.0 适配层
  schemas/       # zod 参数校验
  server/        # stdio/http 双入口
  services/      # 领域服务
  tools/         # MCP 工具实现

8. 注意事项

  • 当前实现按禅道 API V1.0 常见 REST 路径封装(/tokens、/bugs、/products)。

  • 解决 Bug:官方 v1 接口为 POST /bugs/{id}/resolve(不是 PUT)。若误用 PUT,可能出现 HTTP 成功但禅道未真正更新状态的情况。

  • 如果你的禅道实例路径或鉴权字段有差异,可在 src/adapters/zentaoApiV1.ts 适配。

Available Tools

7 tools
activateBugB

激活(重新打开)Bug,对应禅道 API v1:POST /bugs/{id}/active。适用于已解决/已关闭后重新激活。

Inputs: bugId (required), assignedTo, openedBuild, comment.

getBugDetailB
Read-only

查看单个 bug 详情。

Inputs: bugId (required).

getMyBugsB
Read-only

按状态与产品筛选我的 bug 列表。

Inputs: status, productId.

getProductsB
Read-only

获取禅道产品列表。

Inputs: no named parameters.

healthCheckB
Read-only

检查当前会话与服务可用性。

Inputs: no named parameters.

initZentaoC

初始化禅道连接并登录(支持 password 或 token)。

Inputs: baseUrl, account, password, token.

resolveBugC

提交 Bug 解决动作(fixed/notrepro/duplicate/...)。

Inputs: bugId (required), resolution (required).

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no ambiguity. activateBug, resolveBug, getBugDetail, and getMyBugs handle different bug lifecycle stages and views, while getProducts, healthCheck, and initZentao cover separate administrative and setup functions. The descriptions make it easy to distinguish between tools like activateBug (reopen) and resolveBug (close with resolution).

    Naming Consistency4/5

    The naming follows a mostly consistent verb_noun pattern with minor deviations. Tools like activateBug, getBugDetail, getMyBugs, getProducts, and resolveBug use clear action-object naming. However, healthCheck and initZentao deviate slightly by using compound nouns without verbs, though they remain readable and intuitive.

    Tool Count5/5

    With 7 tools, this server is well-scoped for bug tracking and system management in ZenTao. Each tool earns its place by covering essential operations: bug lifecycle (activate, resolve, view), product listing, and system setup/health. The count is neither too sparse nor bloated, fitting the domain appropriately.

    Completeness4/5

    The tool set provides strong coverage for bug management with create, read, update (activate/resolve), and delete implied through resolution. Minor gaps exist, such as no explicit tool for creating bugs or managing other entities like tasks or users, but agents can work around this with the available tools for core workflows.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      Not graded
      maintenance
      Enables direct integration with Zentao bug tracking systems through Cursor. Supports authentication, bug retrieval, searching, and listing operations for comprehensive bug management through natural language.
      5
      7 npm
      -
    • F
      license
      A
      quality
      B
      maintenance
      Enables interaction with ZenTao project management system through RESTful APIs. Supports listing products, managing bugs, viewing statistics, and filtering personal bug assignments through natural language.
      4
      30 npm
      16
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to manage Zentao bugs, requirements, and test cases through natural language interactions. It supports querying, creating, and updating various Zentao data entities including products, projects, and executions.
      12
      MIT