ZenTao User MCP (Python)

一个用 Python 实现的禅道用户管理 MCP 服务。项目通过禅道 API v1 提供 Token 获取、当前用户查询、用户列表查询，以及用户的创建、更新和删除能力；可使用 stdio 或 Streamable HTTP 两种传输方式。

功能

zentao_user_list 可选参数为 page 和 limit；创建与更新工具的完整参数可由 MCP 客户端自动读取。调用写操作前，请先确认所连接的禅道环境和用户 ID。

Related MCP server: zentao-mcp

环境要求

• Python 3.10 或更高版本（推荐 Python 3.12）

• 可访问的禅道实例，并已启用 API v1

• 禅道账号具有相应的用户读取或管理权限

• 仅运行可选示例时需要 Node.js/npm 和对应的大模型 API Key

快速开始

1. 创建虚拟环境并安装依赖

Windows PowerShell：

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

macOS/Linux：

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

2. 配置禅道连接

复制示例配置：

Copy-Item .env.example .env

macOS/Linux 使用：

cp .env.example .env

然后编辑 .env：

ZENTAO_URL=https://zentao.example.com
ZENTAO_ACCOUNT=admin
ZENTAO_PASSWORD=change-me

ZENTAO_URL 支持以下形式：

• https://zentao.example.com

• https://zentao.example.com/zentao

• https://zentao.example.com/zentao/api.php/v1

程序会将前两种形式自动规范化为 API v1 地址。.env 已被 Git 忽略，请勿把真实账号、密码或 API Key 写入 README、源码或提交记录。

stdio 模式

stdio 服务端通常由 Codex、Claude Desktop 等 MCP 客户端启动，无需提前在终端中单独运行。 在支持 MCP 的客户端中添加以下配置，并将路径替换为本机绝对路径：

{
  "mcpServers": {
    "zentao": {
      "command": "C:\\absolute\\path\\zentao-user-mcp-python\\.venv\\Scripts\\python.exe",
      "args": ["-m", "zentao.zentao_server_stdio"],
      "cwd": "C:\\absolute\\path\\zentao-user-mcp-python"
    }
  }
}

macOS/Linux 将 command 改为虚拟环境中的 .venv/bin/python，并把 cwd 设为项目根目录。服务始终从项目根目录加载 .env。

Streamable HTTP 模式

从项目根目录启动服务：

python -m zentao.zentao_server_http

默认端点为 http://127.0.0.1:8000/mcp。支持通过环境变量修改监听地址和端口：

MCP_HOST=127.0.0.1
MCP_PORT=8000

HTTP 模式没有应用层鉴权。如果确实需要跨机器访问，应部署在可信网络内，并在前置网关配置 TLS、身份认证和访问控制；不要直接使用 0.0.0.0 裸露到公网。

客户端示例

客户端示例使用 LangChain 和大模型，不是运行 MCP 服务端所必需。先安装可选依赖：

python -m pip install -r requirements-examples.txt

禅道 stdio 客户端

从项目根目录运行：

python -m zentao.zentao_client_stdio

该客户端会自动启动 zentao.zentao_server_stdio 子进程，不要再单独启动 stdio 服务端。

禅道 HTTP 客户端

先按上一节启动 HTTP 服务端，再在另一个终端运行：

python -m zentao.zentao_client_http

客户端默认连接 http://127.0.0.1:8000/mcp，可通过 ZENTAO_MCP_URL 修改地址。

其他示例

• example_amap_client_http.py：连接远程高德 MCP 服务，需要 AMAP_API_KEY。

• example_playwright_client_stdio.py：通过 stdio 启动 Playwright MCP，需要 Node.js/npm。

这些客户端还需要在 .env 中配置各自使用的大模型 API Key。

项目结构

.
|-- zentao/
|   |-- __init__.py
|   |-- client.py                         # 禅道 REST API 客户端，不是 MCP 客户端
|   |-- zentao_server_stdio.py           # 禅道 MCP 服务端（stdio）
|   |-- zentao_client_stdio.py           # 禅道 MCP 客户端示例（stdio）
|   |-- zentao_server_http.py            # 禅道 MCP 服务端（Streamable HTTP）
|   `-- zentao_client_http.py            # 禅道 MCP 客户端示例（Streamable HTTP）
|-- example_amap_client_http.py           # 高德 MCP HTTP 客户端示例
|-- example_playwright_client_stdio.py    # Playwright MCP stdio 客户端示例
|-- tests/
|   `-- test_client.py                    # 禅道 REST API 客户端单元测试
|-- requirements.txt                      # 核心服务依赖
`-- requirements-examples.txt             # 可选客户端依赖

client 和 server 表示 MCP 中的角色，stdio 和 http 表示连接方式，并非两类客户端。 zentao_client_stdio.py 会启动对应的 stdio 服务端；zentao_client_http.py 则连接已经启动的 HTTP 服务端。 zentao/client.py 供两个服务端调用禅道 REST API，不参与 MCP 客户端连接。

验证

python -m unittest discover -s tests -v
python -m compileall -q zentao tests example_amap_client_http.py example_playwright_client_stdio.py

单元测试不连接真实禅道，不会创建、修改或删除用户。首次接入真实环境时，建议先使用只读工具验证 URL、权限和返回格式。

常见问题

返回 401 或 403

确认账号密码、Token 以及禅道账号权限正确，并检查实例是否允许 API 访问。

返回 404

确认 ZENTAO_URL 的部署路径。程序默认将纯域名补全为 /zentao/api.php/v1；如果禅道安装在其他子路径，请直接填写完整的 /api.php/v1 地址。

MCP 客户端无法启动 stdio 服务

确认 MCP 配置中的 Python 路径和项目根目录 cwd 正确。也可以在项目根目录执行 python -m zentao.zentao_server_stdio 检查依赖和 .env；进程正常启动后会等待 MCP 消息。stdio 协议使用标准输出通信，启动日志会写入标准错误。

许可证

当前仓库尚未附带开源许可证。公开可见不等于允许复制、修改或分发；正式发布前请根据你的授权意图选择并添加 LICENSE。