mcp-server-zuuna

mcp-server-zuuna

面向 Agent 的 Zuuna 看板访问——一个 Model Context Protocol 服务，让编码 Agent （Claude Code、Cursor、Codex）直接读取和操作 Zuuna 看板。

Agent 负责操作看板，Git 确保一切真实可信。

Agent 通过此 MCP 服务读取看板，使用自己的编码工具在代码仓库中完成工作；PR 合并后，Zuuna 看板上的规则会移动卡片。Zuuna 提供界面和可验证的看板事实——代码由 Agent 编写，而非 Zuuna。

状态

已可运行并经过测试，且已发布到 npm（npx -y mcp-server-zuuna），并已对令牌模型、作用域和工具接口进行身份验证审查。如果想自行修改，可从源码运行（见下文）。

托管式替代方案

相同的 73 个工具也提供免安装版本：Zuuna 在 app.zuuna.de/mcp 提供托管式 MCP 连接器（OAuth 登录，需要 Developer 套餐）。直接将 Claude Code、Cursor 或 Codex 指向该 URL，即可跳过下方的令牌和 npx 命令。此软件包适用于确实需要本地进程的情况：CI 运行器、隔离网络中的 Agent，或需要使用普通 bearer token 而非 OAuth 登录的工作流。请参阅 面向 AI Agent 的看板，了解这两种方式的并列介绍。

工具

共 73 个工具，按类别分组。所有工具都可使用任何有效令牌；Scopes 列出了令牌还必须具备的权限。标记为破坏性的 8 个工具必须提供明确的 confirm: true 参数，否则不会运行。

身份

工具	方法 + 路径	Scopes
zuuna_me	GET /api/v1/me	无

群组

工具	方法 + 路径	Scopes
zuuna_list_groups	GET /api/v1/groups	boards:read
zuuna_list_group_members	GET /api/v1/groups/{groupId}/members	boards:read
zuuna_list_epics	GET /api/v1/groups/{groupId}/epics	boards:read
zuuna_create_epic	POST /api/v1/groups/{groupId}/epics	cards:write
zuuna_update_epic	PATCH /api/v1/groups/{groupId}/epics/{epicId}	cards:write
zuuna_list_group_cards	GET /api/v1/groups/{groupId}/cards	cards:read

看板

工具	方法 + 路径	Scopes
zuuna_boards	GET /api/v1/boards	boards:read
zuuna_board	GET /api/v1/boards/{id}/columns + GET /api/v1/boards/{id}/cards	boards:read、cards:read
zuuna_create_board	POST /api/v1/boards	boards:write
zuuna_list_columns	GET /api/v1/boards/{boardId}/columns	boards:read
zuuna_list_board_fields	GET /api/v1/boards/{boardId}/fields	boards:read
zuuna_create_column	POST /api/v1/boards/{boardId}/columns	boards:write
zuuna_list_automations	GET /api/v1/boards/{boardId}/automations	boards:read

卡片

工具	方法 + 路径	权限范围
zuuna_card	GET /api/v1/cards/{idOrKey}	cards:read
zuuna_list_board_cards	GET /api/v1/boards/{boardId}/cards	cards:read
zuuna_search_cards	GET /api/v1/cards	cards:read
zuuna_create_card	POST /api/v1/boards/{boardId}/cards	cards:write
zuuna_create_cards	POST /api/v1/boards/{boardId}/cards ({"cards":[...]})	cards:write
zuuna_update_card	PATCH /api/v1/cards/{idOrKey}	cards:write
zuuna_move_card	PATCH /api/v1/cards/{idOrKey}	cards:write
zuuna_move_card_to_board	POST /api/v1/cards/{cardId}/move	cards:write
zuuna_archive_card	POST /api/v1/cards/{cardId}/archive	cards:write
zuuna_unarchive_card	DELETE /api/v1/cards/{cardId}/archive	cards:write
zuuna_delete_card （破坏性操作）	DELETE /api/v1/cards/{cardId}	cards:write
zuuna_restore_card	POST /api/v1/cards/{cardId}/restore	cards:write

评论

工具	方法 + 路径	权限范围
zuuna_list_comments	GET /api/v1/cards/{cardId}/comments	comments:read
zuuna_comment	POST /api/v1/cards/{cardId}/comments	comments:write

检查清单

工具	方法 + 路径	权限范围
zuuna_list_checklist	GET /api/v1/cards/{cardId}/checklist	cards:read
zuuna_add_checklist_item	POST /api/v1/cards/{cardId}/checklist	cards:write
zuuna_update_checklist_item	PATCH /api/v1/cards/{cardId}/checklist/{itemId}	cards:write
zuuna_delete_checklist_item （破坏性操作）	DELETE /api/v1/cards/{cardId}/checklist/{itemId}	cards:write

关联关系

工具	方法 + 路径	权限范围
zuuna_list_relations	GET /api/v1/cards/{cardId}/relations	cards:read
zuuna_add_relation	POST /api/v1/cards/{cardId}/relations	cards:write
zuuna_delete_relation （破坏性操作）	DELETE /api/v1/cards/{cardId}/relations/{linkId}	cards:write

附件

自 ZNA-2170 起支持上传：zuuna_upload_attachment 可接收本地文件路径，或 base64 字节数据及文件名。列表和获取操作仍只返回元数据，不会返回文件内容本身。

工具	方法 + 路径	权限范围
zuuna_list_attachments	GET /api/v1/cards/{cardId}/attachments	cards:read
zuuna_upload_attachment	POST /api/v1/cards/{cardId}/attachments	cards:write
zuuna_get_attachment	GET /api/v1/cards/{cardId}/attachments/{attachmentId}（仅元数据）	cards:read
zuuna_delete_attachment （破坏性操作）	DELETE /api/v1/cards/{cardId}/attachments/{attachmentId}	cards:write

时间跟踪

工具	方法 + 路径	权限范围
zuuna_list_card_time	GET /api/v1/cards/{cardId}/time	time:read
zuuna_log_time	POST /api/v1/cards/{cardId}/time	time:write
zuuna_start_timer	POST /api/v1/cards/{cardId}/time	time:write
zuuna_stop_timer	POST /api/v1/cards/{cardId}/time	time:write
zuuna_list_active_timers	GET /api/v1/time/active	time:read
zuuna_update_time_entry	PATCH /api/v1/time/{entryId}	time:write
zuuna_delete_time_entry （破坏性操作）	DELETE /api/v1/time/{entryId}	time:write
zuuna_import_time_entries	POST /api/v1/time/entries	time:write

Sprint

工具	方法 + 路径	权限范围
zuuna_list_sprints	GET /api/v1/sprints	boards:read
zuuna_get_sprint	GET /api/v1/sprints/{sprintId}	boards:read
zuuna_create_sprint	POST /api/v1/sprints	cards:write
zuuna_update_sprint	PATCH /api/v1/sprints/{sprintId}	cards:write
zuuna_add_cards_to_sprint	POST /api/v1/sprints/{sprintId}/cards	cards:write
zuuna_remove_card_from_sprint	DELETE /api/v1/sprints/{sprintId}/cards/{cardId}	cards:write

周期性卡片

工具	方法 + 路径	范围
zuuna_list_recurring_cards	GET /api/v1/boards/{boardId}/recurring	boards:read
zuuna_create_recurring_card	POST /api/v1/boards/{boardId}/recurring	cards:write
zuuna_update_recurring_card	PATCH /api/v1/recurring/{id}	cards:write
zuuna_delete_recurring_card （有破坏性）	DELETE /api/v1/recurring/{id}	cards:write

发布版本

工具	方法 + 路径	范围
zuuna_list_releases	GET /api/v1/releases	boards:read
zuuna_get_release	GET /api/v1/releases/{releaseId}	boards:read
zuuna_create_release	POST /api/v1/releases	releases:write
zuuna_update_release	PATCH /api/v1/releases/{releaseId}	releases:write
zuuna_delete_release （有破坏性）	DELETE /api/v1/releases/{releaseId}	releases:write

部署

仅供观察：这里没有“触发部署”工具，托管连接器中也没有（见“范围说明”）。

工具	方法 + 路径	范围
zuuna_list_deployments	GET /api/v1/deployments	boards:read
zuuna_report_deployment	POST /api/v1/deployments	deployments:write

Webhook

工具	方法 + 路径	范围
zuuna_list_webhooks	GET /api/v1/webhooks	webhooks:manage
zuuna_create_webhook	POST /api/v1/webhooks	webhooks:manage
zuuna_update_webhook	PATCH /api/v1/webhooks/{id}	webhooks:manage
zuuna_delete_webhook （有破坏性）	DELETE /api/v1/webhooks/{id}	webhooks:manage
zuuna_test_webhook	POST /api/v1/webhooks/{id}/test	webhooks:manage
zuuna_list_webhook_deliveries	GET /api/v1/webhooks/{id}/deliveries	webhooks:manage

看板上的 Git

将提交、分支、PR 和 CI 状态关联到卡片。这些操作本身都不会移动卡片（见“范围说明”）。

工具	方法 + 路径	范围
zuuna_link_git_branches	POST /api/v1/git/branches	git:write
zuuna_report_ci_checks	POST /api/v1/git/checks	git:write
zuuna_record_git_events	POST /api/v1/git/events	git:write

行为说明：

• 错误会作为 MCP 工具错误返回，并包含 API 自身的消息（v1 信封中的 message，以及状态和机器可读的 code）——例如，HARD WIP 限制拒绝移动时会返回 409 wip_limit_reached。
• 每个请求只发一次，不会重试：绝不会重新发送 4xx 响应。请求会在 15 s 后超时 （可配置），并作为网络错误显示。
• 卡片显示键（如 ZNA-2001）可用于任何指定卡片的操作——v1 API 接受 该键作为标识符。
• zuuna_board 会对卡片列表分页（每页 200 张卡片，这是 v1 API 自身的上限），因此大型 看板不会使 Agent 的上下文过载。如果某页不是整个看板的全部内容，响应会包含 cardsTruncated: true，并附带 nextCursor；将其作为 cardsCursor 传回即可 获取下一页。
• zuuna_create_card 接受可选的、由客户端选择的 idempotencyKey：如果响应丢失或收到 5xx 后使用相同的键重新发送请求，将返回原卡片（200），而不是创建重复卡片。
• zuuna_me 还会返回一个 hiddenTools 列表：其中列出此令牌的范围所隐藏的每个工具， 以及解锁该工具所需的范围（与启动时适用的范围门控边界相同）。
• 启动时，服务会读取自身令牌的范围（GET /api/v1/me），并且只注册这些范围所覆盖的工具， 这与托管连接器应用的范围门控相同。如果读取失败（尚无网络连接、令牌无效），则会改为注册 所有工具，并向 stderr 打印一行说明；无论注册了什么，每次调用仍由 API 强制执行权限检查。
• 除工具外还提供了五个提示词（session_start、session_end、triage_board、 standup_summary、plan_sprint），可作为支持 MCP 提示词的客户端的起点；直接使用工具 并不需要这些提示词。

设置

你需要 Zuuna 工作区的 API 令牌。根据 Agent 应获准执行的操作，为令牌授予相应权限范围——只读观察者只需要 boards:read + cards:read。

每个客户端通过环境变量配置服务：

变量	默认值	含义
ZUUNA_API_TOKEN	—（必填）	Bearer API 令牌
ZUUNA_BASE_URL	https://app.zuuna.de	Zuuna 基础 URL——必须是绝对 http(s) URL（无效值会在启动时导致失败）；使用普通 http 的值会在 stderr 中输出明文令牌警告
ZUUNA_TIMEOUT_MS	15000	每次请求的超时时间

Claude Code

claude mcp add zuuna \
  -e ZUUNA_API_TOKEN=zk_live_your_token \
  -- npx -y mcp-server-zuuna

或在项目的 .mcp.json 中：

{
  "mcpServers": {
    "zuuna": {
      "command": "npx",
      "args": ["-y", "mcp-server-zuuna"],
      "env": { "ZUUNA_API_TOKEN": "zk_live_your_token" }
    }
  }
}

Cursor

在 ~/.cursor/mcp.json（或项目的 .cursor/mcp.json）中：

{
  "mcpServers": {
    "zuuna": {
      "command": "npx",
      "args": ["-y", "mcp-server-zuuna"],
      "env": { "ZUUNA_API_TOKEN": "zk_live_your_token" }
    }
  }
}

Codex

在 ~/.codex/config.toml 中：

[mcp_servers.zuuna]
command = "npx"
args = ["-y", "mcp-server-zuuna"]
env = { "ZUUNA_API_TOKEN" = "zk_live_your_token" }

从源代码运行

git clone https://github.com/kenzotp/mcp-server-zuuna
cd mcp-server-zuuna && npm install && npm run build

然后将客户端指向构建好的二进制文件，而不是 npx：

claude mcp add zuuna -e ZUUNA_API_TOKEN=zk_live_your_token -- node /path/to/mcp-server-zuuna/dist/index.js

工作循环

1. zuuna_board — Agent 查看看板并选择一张卡片（或者你告诉它：“处理 ZNA-2001”）。
2. Agent 使用自己的工具在你的代码仓库中编写代码，并在提交中引用卡片键。
3. PR 合并后，Git 中的事实会推动卡片流转：Zuuna 的 Git 集成（webhook/CLI）会将提交和 PR 关联到卡片，看板上的规则（例如“PR 已合并 → 移至 Done”）会推动卡片流转。关联开箱即用；你只需在看板的自动化中添加一条规则。此后，Agent 无需再手动操作看板，看板也不会与代码仓库脱节。

指南

• 面向 AI Agent 的看板：Agent 设置看板、创建和移动卡片、发表评论并记录工时；之后由看板规则推动卡片流转。
• Claude Code 跨会话项目管理：通过 CLAUDE.md 中的例行流程，将应用的计划保存在看板上，让每个新会话都能从上一个会话停止的地方继续。
• 面向 AI Agent 的 Zuuna：从卡片到 PR 合并的工作循环，提供英文和德文版本。

明确的功能范围

目前仍没有可触发部署的工具。zuuna_report_deployment（deployments:write）只能记录流水线已经执行的操作（构建、成功、失败）；实际发布仍由你自己的 CI 负责，而不是 Agent。

现在有三个 git:write 工具，但它们的功能比名称所暗示的更有限：

• zuuna_record_git_events 和 zuuna_report_ci_checks 会将提交/分支/PR 历史及 CI 状态关联到智能提交引用或描述所指明的卡片。
• zuuna_link_git_branches 通过一次调用，整体替换某个代码仓库的所有进行中分支快照。

这三个工具都不会移动卡片。只有看板规则匹配到卡片时（见上文“工作循环”），或直接调用 zuuna_move_card / zuuna_update_card 时，卡片才会移动。此处的自动化本身也只能读取（zuuna_list_automations）：没有工具可以创建、编辑或停用自动化。附件上传通过 multipart（ZNA-2170）完成，并遵循 REST 路由自身的限制和错误处理；没有任何工具会读取文件内容。

开发

npm install
npm run lint     # eslint
npm run build    # tsc -> dist/
npm test         # vitest, fully mocked (no network)

可选的实时冒烟测试，严格只读（仅调用 GET /me 和 GET /boards——绝不会创建、移动或评论任何内容）：

ZUUNA_E2E=1 ZUUNA_API_TOKEN=zk_live_your_token npm run test:e2e

需要 Node.js >= 20。

许可证

MIT