@staragent/zentao-mcp

给 Cursor / Claude 用的禅道 MCP。用账号密码换 REST Token，在项目 → 执行下查、建、改需求、任务、Bug、测试单。

需要 Node >= 18，无第三方依赖。

安装

npm 包：@staragent/zentao-mcp。请用 1.0.11+（latest）。业务 CRUD 一律 REST（创建需求用 POST /api.php/v2/stories）。仅「拉产品模块」走网页会话。不要用 1.0.7/1.0.8（网页建需求会「登录已超时」）。

{
  "mcpServers": {
    "zentao": {
      "command": "npx",
      "args": ["-y", "--prefer-online", "@staragent/[email protected]"],
      "env": {
        "NPM_CONFIG_REGISTRY": "https://registry.npmjs.org/",
        "ZENTAO_URL": "http://你的禅道地址/zentao",
        "ZENTAO_ACCOUNT": "账号",
        "ZENTAO_PASSWORD": "密码"
      }
    }
  }
}

可选：再配项目全名、执行全名，调用时就不用每次传 id。

"ZENTAO_PROJECT": "2026年公司级本体平台研发项目",
"ZENTAO_EXECUTION": "本体平台四期"

改完配置后刷新 Cursor 的 MCP。

环境变量

| 变量 | 必填 | 说明 | |---|---|---| | ZENTAO_URL | 是 | 禅道根地址，一般带 /zentao | | ZENTAO_ACCOUNT | 是 | 登录账号 | | ZENTAO_PASSWORD | 是 | 登录密码 | | ZENTAO_TOKEN | 否 | 已有 REST Token 时可跳过登录。进程启动时读一次，Cursor 单人用法用这个 | | zentao_token（工具参数，不在 schema 里） | 否 | 本次调用的 REST Token，优先于 ZENTAO_TOKEN，用完即丢。拉模块仍要进程里的 ZENTAO_ACCOUNT + ZENTAO_PASSWORD（Token 建不了网页会话） | | ZENTAO_PROJECT | 否 | 禅道项目全名，用来解析 project_id | | ZENTAO_EXECUTION | 否 | 禅道执行全名，用来解析 execution_id。配了执行名时，还要能解析到项目（ZENTAO_PROJECT 或调用时传 project_id） |

名称按全名精确匹配；匹配不到或多个同名时会报错，请改用 id。

未配置名称时怎么用

1. zentao_list_projects（可用 keyword）→ 得到 project_id
2. zentao_list_executions（传上一步的 project_id）→ 得到 execution_id
3. 之后列/建需求、任务、Bug、测试单时带上这两个 id

单次调用也可用参数 project_name / execution_name，优先于环境变量。

工具

| 域 | 工具 | |---|---| | 账号 | zentao_whoami | | 项目 | zentao_list_projects zentao_get_project | | 执行 | zentao_list_executions zentao_get_execution zentao_create_execution zentao_update_execution | | 需求 | zentao_list_stories zentao_get_story zentao_create_story zentao_update_story | | 任务 | zentao_list_tasks zentao_get_task zentao_create_task zentao_update_task | | Bug | zentao_list_bugs zentao_list_modules zentao_get_bug zentao_create_bug zentao_update_bug | | 测试单 | zentao_list_builds zentao_list_testtasks zentao_get_testtask zentao_create_testtask zentao_update_testtask |

按 id 查详情的工具（如 zentao_get_story）只需对应资源 id。

提 Bug：传了 module（数字 id）则直接提交。未传时用网页同一套接口 tree-ajaxGetOptionMenu 拉模块（不用 REST GET /api.php/v1/modules，避免角色无权限）。再用标题/步骤或 module_name 匹配；拉不到列表则从本执行已有 Bug 推断，或省略模块。影响版本 opened_build 不传则用「主干」(trunk)。