mcp-zentao

面向禅道 11.3 Legacy Session API 的 Model Context Protocol（MCP）服务器。它让 Codex、Claude Desktop、Cursor 等 MCP 客户端可以读取和操作禅道中的任务、Bug、需求、测试用例和测试单。

本项目是基于 MaxenLin/mcp-zentao-11-3@1.0.5 的非官方派生版本，保留原项目 MIT 许可证和版权声明。

兼容范围

本项目不会自动探测路由模式。部分禅道或代理服务会对错误路由返回 HTTP 200 的 HTML 页面，自动探测可能把登录页或错误页误判为可用接口，因此需要显式配置。

Related MCP server: 禅道 MCP Server

环境要求

• Node.js 20 或更高版本

• 可访问目标禅道服务的网络环境

• 一个具有所需禅道权限的账号

推荐使用方式

客户端通过固定 npm 版本启动，避免 latest 更新导致行为变化：

{
  "mcpServers": {
    "zentao": {
      "command": "npx",
      "args": ["-y", "mcp-zentao@1.0.0"],
      "env": {
        "ZENTAO_URL": "https://zentao.example.com",
        "ZENTAO_USERNAME": "your-username",
        "ZENTAO_PASSWORD": "your-password",
        "ZENTAO_REQUEST_TYPE": "GET",
        "ZENTAO_ENTRY": "index.php"
      }
    }
  }
}

配置保存位置由 MCP 客户端决定。修改配置后需要重启对应客户端。

也可以全局安装后使用 CLI：

npm install -g mcp-zentao@1.0.0

{
  "mcpServers": {
    "zentao": {
      "command": "mcp-zentao",
      "args": [],
      "env": {
        "ZENTAO_URL": "https://zentao.example.com",
        "ZENTAO_USERNAME": "your-username",
        "ZENTAO_PASSWORD": "your-password",
        "ZENTAO_REQUEST_TYPE": "GET",
        "ZENTAO_ENTRY": "index.php"
      }
    }
  }
}

配置说明

ZENTAO_URL

填写禅道应用根地址，不要把 API 路径或 index.php 写进去。

• 禅道部署在站点根路径：https://zentao.example.com

• 禅道确实部署在 /zentao 子路径：https://example.com/zentao

只有浏览器实际访问地址包含 /zentao 时才保留该路径。不要因为项目名称是禅道就手工追加 /zentao。

ZENTAO_USERNAME 和 ZENTAO_PASSWORD

禅道登录账号和密码。凭证只应保存在本地 MCP 客户端配置或本地配置文件中，不要提交到 Git 仓库。

ZENTAO_REQUEST_TYPE

支持以下值：

• GET：默认值，使用具名查询参数访问 Legacy Session API。

• PATH_INFO：使用 module-method-params.json 形式访问。

ZENTAO_ENTRY

GET 模式的相对入口，默认值为 index.php。如果部署通过自定义入口转发，可以填写 gateway.php 或 gateway/index.php。

PATH_INFO 模式不会使用该配置。

默认配置

省略路由配置时等价于：

ZENTAO_REQUEST_TYPE=GET
ZENTAO_ENTRY=index.php

本地配置文件

除了环境变量，也可以使用 ~/.zentao/config.json：

{
  "url": "https://zentao.example.com",
  "username": "your-username",
  "password": "your-password",
  "apiVersion": "legacy",
  "requestType": "GET",
  "entry": "index.php"
}

完整的环境变量连接配置优先于配置文件。使用配置文件时，非空环境变量会按字段覆盖文件内容。

功能范围

当前 MCP 注册 48 个工具，主要包括：

• 配置初始化和脱敏后的配置查询

• 我的任务、任务详情、任务更新和完成

• 我的 Bug、Bug 详情、产品 Bug 和 Bug 解决

• 产品、需求、需求搜索和需求详情

• 测试用例、测试单、执行结果和用例执行

• 需求、Bug、任务之间的关联查询

• 批量任务和 Bug 操作

• 统计、开发上下文、Markdown 摘要和数据导出

• 复杂度、优先级、工作量及下一步建议分析

• 代码提示、测试提示和代码审查清单生成

部分工具会修改禅道数据。调用更新、完成、解决、创建或执行类工具前，请检查客户端展示的参数并确认当前账号权限。

开发与验证

npm ci
npm test

仅构建：

npm run build

检查 npm 发布内容：

npm pack --dry-run

npm 包只包含 dist/、README.md、LICENSE 和 package.json。源码、测试、凭证、本地 MCP 配置和 node_modules 不进入发布包。

常见问题

MCP 启动失败并提示找不到 node 或 npx

确认 Node.js 20+ 已安装，并在启动 MCP 客户端的环境中执行：

node --version
npx --version

Windows 安装 Node.js 后通常需要完全退出并重新打开 MCP 客户端，使新的 PATH 生效。

GET 模式返回 HTML 或 404

依次确认：

1. ZENTAO_URL 是否为真实应用根地址。

2. 是否错误追加或遗漏实际部署的 /zentao 子路径。

3. ZENTAO_ENTRY 是否与服务入口一致，常见值为 index.php。

4. 服务是否确实启用了 GET 路由；如果只支持 PATH_INFO，显式改为 PATH_INFO。

PATH_INFO 模式返回 404

这通常表示服务器、反向代理或当前禅道部署没有启用 PATH_INFO。请改用 GET，并设置正确的 ZENTAO_ENTRY。

升级与回滚

建议在客户端中固定精确版本：

mcp-zentao@1.0.0

升级时先修改版本号并重启客户端。如果新版本不适配当前部署，将配置恢复到上一个已验证版本即可。开发环境也可以直接回滚为本地入口：

node <project-directory>/dist/index.js

项目来源与主要改动

本项目以 MaxenLin/mcp-zentao-11-3 的 1.0.5 版本为基线，主要增加或完善：

• 禅道 11.3 GET 路由的位置参数到具名参数转换

• GET、PATH_INFO 和自定义 GET 入口配置

• 路由及配置校验、错误信息和配置脱敏

• 48 个 MCP 工具契约及 Legacy API 回归测试

• 独立 npm 包、GitHub 仓库和版本线

本项目不是禅道官方项目，也不代表原项目作者对该派生版本提供支持或背书。

许可证

MIT。原始版权声明保留在 LICENSE 中。

相关链接

• 本项目 GitHub 仓库

• 上游项目

• Model Context Protocol

• 禅道官网