MCP Server Zuuna

mcp-server-zuuna

Agent-native board access for [Zuuna](https://zuuna.de/en/kanban-board-for-ai-agents?utm_source=npm&utm_medium=referral&utm_campaign=mcp-server-readme) — a Model Context Protocol server that lets coding agents (Claude Code, Cursor, Codex) read and work a Zuuna board directly.

Agents work the board. Git keeps it honest.

The agent reads the board via this MCP server, does the work in the repo with its own

coding tools, and when the PR merges, a rule on your Zuuna board moves the card. Zuuna

provides the interface and the verifiable board truth — the agent writes the code, not Zuuna.

Status

Working and tested, and published on npm (npx -y mcp-server-zuuna) after an auth review of the token model, scopes and tool surface. Run from source (bottom) if you want to hack on it.

Hosted alternative

The same 73 tools are also available with nothing to install: Zuuna runs a hosted MCP connector at app.zuuna.de/mcp (OAuth sign-in, Developer plan). Point Claude Code, Cursor or Codex at that URL directly and skip the token and the npx line below. This package exists for the case that does need a local process: a CI runner, an air-gapped agent, or a workflow that wants a plain bearer token instead of an OAuth sign-in. See Kanban board for AI agents for both routes side by side.

Tools

73 tools, grouped by area. Every tool works with any valid token; the Scopes column lists what else the token must carry. The 8 marked destructive refuse to run without an explicit confirm: true argument.

Identity

Groups

Boards

Cards

Comments

Checklist

Relations

Attachments

Upload included since ZNA-2170: zuuna_upload_attachment takes a local file path, or base64 bytes plus a filename. List and get still return metadata only, never the bytes themselves.

Time tracking

Sprints

Recurring cards

Releases

Deployments

Observation only: there is no "trigger a deploy" tool, on the hosted connector either (see "Honest scope").

Webhooks

Git on board

Link commits, branches, PRs and CI status to cards. None of these move a card by themselves (see "Honest scope").

Behavioral notes:

• Errors come back as MCP tool errors with the API's own message (the v1 envelope's message plus status and machine code) — e.g. 409 wip_limit_reached when a HARD WIP limit refuses a move.
• One request, no retries: 4xx answers are never re-sent. Requests time out after 15 s (configurable) and surface as network errors.
• Card display keys like ZNA-2001 work anywhere a card is addressed — the v1 API accepts the key as the handle.
• zuuna_board pages the card list (200 cards per page, the v1 API's own cap) so a big board cannot flood the agent's context. When a page is not the whole board, the response says cardsTruncated: true and carries nextCursor; send it back as cardsCursor to fetch the next page.
• zuuna_create_card accepts an optional client-chosen idempotencyKey: re-sending the same key after a lost response or a 5xx returns the original card (200) instead of minting a duplicate.
• zuuna_me also returns a hiddenTools list: every tool this token's scopes hide, each with the scope or scopes that would unlock it (the same boundary the startup scope-gating applies).
• At startup the server reads its own token's scopes (GET /api/v1/me) and registers only the tools they cover, the same scope gating the hosted connector applies. If that read fails (no network yet, an invalid token) it registers every tool instead and prints one line to stderr saying so; every call is still enforced by the API regardless of what got registered.
• Five prompts ship alongside the tools (session_start, session_end, triage_board, standup_summary, plan_sprint), starting points for a client that surfaces MCP prompts, not required for using the tools directly.

Setup

You need an API token from your Zuuna workspace. Give it the scopes for what the agent should be allowed to do — a read-only observer needs only boards:read + cards:read.

The server is configured per client via environment variables:

Claude Code

claude mcp add zuuna \

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

or in the project's .mcp.json:

{

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