ZenTao User MCP (Python)

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

功能

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

Related MCP server: Onde Inference MCP Server

环境要求

• 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 模式

直接运行：

python server_stdio.py

在支持 MCP 的客户端中添加服务器。下面是通用 JSON 配置示例，路径需要替换为本机绝对路径：

{
  "mcpServers": {
    "zentao": {
      "command": "C:\\absolute\\path\\.venv\\Scripts\\python.exe",
      "args": ["C:\\absolute\\path\\server_stdio.py"]
    }
  }
}

macOS/Linux 将 command 改为虚拟环境中的 .venv/bin/python。服务会从项目根目录加载 .env，不依赖 MCP 客户端的当前工作目录。

Streamable HTTP 模式

启动服务：

python server_http.py

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

MCP_HOST=127.0.0.1
MCP_PORT=8000

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

项目结构

.
|-- server_stdio.py              # 禅道 MCP stdio 服务
|-- server_http.py               # 禅道 MCP Streamable HTTP 服务
|-- zentao/
|   |-- client.py                # 禅道 API 请求与 URL 规范化
|   |-- client_mcp.py            # HTTP MCP + 通义千问示例
|   `-- am_mcp.py                # 高德 MCP 出行规划示例
|-- mcp_stdio_server.py          # 最小加法 MCP 示例
|-- mcp_stdio_client.py          # stdio + LangChain 示例
|-- mcp_playwright_client.py     # Playwright MCP + 智谱示例
|-- requirements.txt             # 核心服务依赖
`-- requirements-examples.txt    # 可选示例依赖

示例不是运行禅道 MCP 服务的必要部分。如需运行它们，先安装额外依赖：

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

再按 .env.example 配置对应变量。Playwright MCP 示例还要求系统已安装 Node.js/npm。

验证

python -m unittest discover -s tests -v
python -m compileall -q server_stdio.py server_http.py zentao

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

常见问题

返回 401 或 403

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

返回 404

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

MCP 客户端无法启动 stdio 服务

使用虚拟环境 Python 和 server_stdio.py 的绝对路径，并先在终端中直接运行一次以检查缺失依赖或 .env 配置错误。stdio 协议使用标准输出通信，启动日志会写入标准错误。

许可证

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