禅道任务管理 MCP Server

在 Claude Code / Claude Desktop 中用自然语言操作禅道：查看执行和任务、批量创建/更新/关闭任务，支持上传图片和视频附件。

功能一览

工具	说明
zentao_list_executions	列出所有执行/迭代（Sprint）
zentao_list_tasks	列出指定执行下的全部任务（含状态、优先级、负责人）
zentao_list_users	列出所有用户账号（用于填 assignedTo）
zentao_publish_yaml	从 YAML 批量创建 / 更新 / 关闭任务，支持上传图片和视频

---

安装

要求：Python 3.9+

git clone https://github.com/ruan11223344/zentao-mcp.git
cd zentao-mcp
pip install -r requirements.txt

---

配置

cp .env.example .env

编辑 .env：

ZENTAO_URL=https://your-zentao-server.com
ZENTAO_ACCOUNT=your_account
ZENTAO_PASSWORD=your_password

---

配置到 Claude Code

在 ~/.claude/settings.json 的 mcpServers 中添加：

{
  "mcpServers": {
    "zentao": {
      "command": "python",
      "args": ["/path/to/zentao-mcp/server.py"]
    }
  }
}

也可以不用 .env，直接在配置里写：

{
  "mcpServers": {
    "zentao": {
      "command": "python",
      "args": ["/path/to/zentao-mcp/server.py"],
      "env": {
        "ZENTAO_URL": "https://your-zentao-server.com",
        "ZENTAO_ACCOUNT": "your_account",
        "ZENTAO_PASSWORD": "your_password"
      }
    }
  }
}

---

使用方法（MCP 工具）

查询执行列表

让 Claude 调用 zentao_list_executions，返回所有迭代的 ID、名称、状态和起止日期：

帮我查下禅道执行列表

查询任务列表

列出执行 #5 的所有任务

查询用户列表

禅道里有哪些用户？

---

创建任务

YAML 中不填 id 即为创建新任务：

execution: 5
defaults:
  type: devel
  assignedTo: zhangsan
  pri: 2
  estStarted: "2026-03-16"
  deadline: "2026-03-31"
tasks:
  - name: "用户登录功能开发"
    estimate: 8
    desc: |
      <h3>需求</h3>
      <p>实现用户名/密码登录，支持记住密码。</p>

  - name: "首页 Banner 接口"
    estimate: 4
    assignedTo: lisi     # 单独覆盖负责人
    pri: 1

去重保护：同名任务已存在时自动跳过，不会重复创建。加 force: true 可强制创建。

---

更新任务

YAML 中填写 id 即为更新已有任务：

execution: 5
tasks:
  - id: 123
    name: "用户登录功能开发（更新）"
    pri: 1
    deadline: "2026-03-20"
    desc: |
      <h3>更新说明</h3>
      <p>增加手机号登录支持。</p>

---

关闭任务

填写 id + close 字段即关闭任务，close 的值作为关闭原因：

execution: 5
tasks:
  - id: 123
    close: "功能已开发完成，测试通过"

  - id: 124
    close: "需求变更，不再实现"

---

上传图片（嵌入描述）

图片会上传后嵌入到任务描述中：

execution: 5
tasks:
  - name: "UI 还原问题修复"
    desc: "<p>以下为设计稿与实现对比：</p>"
    images:
      - path: ./screenshots/design.png
        label: "设计稿"
      - path: ./screenshots/actual.png
        label: "实际效果"

---

上传视频（任务附件）

视频会作为文件附件上传到任务，在禅道界面可直接下载：

execution: 5
tasks:
  - id: 123
    videos:
      - ./recordings/bug-demo.mp4

---

预览（dry_run）

dry_run: true 只预览不执行，用于确认任务内容：

帮我预览以下 YAML，不要实际创建：
execution: 5
tasks:
  - name: "测试任务"
    assignedTo: admin

---

混合操作（一次 YAML 同时创建/更新/关闭）

execution: 5
defaults:
  assignedTo: zhangsan
  pri: 3
tasks:
  # 创建新任务
  - name: "新功能 A"
    estimate: 6

  # 更新已有任务
  - id: 100
    name: "已有任务（修改名称）"
    pri: 1

  # 关闭任务
  - id: 101
    close: "已完成"

---

命令行使用（不依赖 Claude）

也可以直接用命令行操作：

# 预览任务（不执行）
python publish.py tasks/my_tasks.yaml

# 执行创建/更新/关闭
python publish.py tasks/my_tasks.yaml --execute

# 覆盖执行 ID
python publish.py tasks/my_tasks.yaml --execute --execution 8

# 强制创建（跳过去重检查）
python publish.py tasks/my_tasks.yaml --execute --force

# 查看执行列表
python publish.py --list-executions

# 查看任务列表
python publish.py --list-tasks 5

# 查看用户列表
python publish.py --list-users

---

YAML 字段说明

顶层字段

字段	说明
execution	执行/迭代 ID（必填）
defaults	任务默认值，被 tasks 中的字段覆盖
tasks	任务列表

任务字段

字段	说明
id	有则更新，无则创建
name	任务名称
assignedTo	负责人账号
pri	优先级（1=紧急 2=高 3=中 4=低）
estimate	预估工时（小时）
type	类型（devel/design/test/doc 等）
estStarted	预计开始日期（YYYY-MM-DD）
deadline	截止日期（YYYY-MM-DD）
desc	描述（支持 HTML）
images	图片列表（嵌入描述）
videos	视频列表（任务附件）
close	填写则关闭任务（值为关闭原因，需同时填 id）

---

支持的禅道版本

禅道 17.x 及以上，需开启 API 访问权限。