mcp-server-zuuna
This MCP server lets an AI agent read and manage Zuuna boards and cards via API, with scope-gated tools and safe card creation.
Identity:
zuuna_mereturns the token's organization, plan, granted scopes, and grace-window deadline.Board listing:
zuuna_boardslists non-archived, non-private boards with id, title, and card key prefix.Board detail:
zuuna_boardreturns columns and a paged 200-card snapshot; supports cursor pagination viacardsCursor.Card detail:
zuuna_cardfetches full card info by key (e.g. ZNA-2001) or id, including description, priority, type, due date, checklist counts, assignees, epic, custom fields, and attachments.Card creation:
zuuna_create_cardcreates cards on a board, optionally in a specific column, with an idempotencyKey for safe retries.Card editing:
zuuna_update_cardchanges title, description, and/or priority.Card moving:
zuuna_move_cardmoves a card to another column by column id or title.Comments:
zuuna_commentadds a comment to a card as the token owner.
Provides tools for linking Git branches, commits, pull requests, and CI status to Zuuna cards.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-server-zuuna show me the cards on the ZNA board in column 'In Progress'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-server-zuuna
Agent-native board access for Zuuna — 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.
Related MCP server: Kanban Zone MCP Server
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
Tool | Method + path | Scopes |
|
| none |
Groups
Tool | Method + path | Scopes |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Boards
Tool | Method + path | Scopes |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Cards
Tool | Method + path | Scopes |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Comments
Tool | Method + path | Scopes |
|
|
|
|
|
|
Checklist
Tool | Method + path | Scopes |
|
|
|
|
|
|
|
|
|
|
|
|
Relations
Tool | Method + path | Scopes |
|
|
|
|
|
|
|
|
|
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.
Tool | Method + path | Scopes |
|
|
|
|
|
|
|
|
|
|
|
|
Time tracking
Tool | Method + path | Scopes |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Sprints
Tool | Method + path | Scopes |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Recurring cards
Tool | Method + path | Scopes |
|
|
|
|
|
|
|
|
|
|
|
|
Releases
Tool | Method + path | Scopes |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Deployments
Observation only: there is no "trigger a deploy" tool, on the hosted connector either (see "Honest scope").
Tool | Method + path | Scopes |
|
|
|
|
|
|
Webhooks
Tool | Method + path | Scopes |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Git on board
Link commits, branches, PRs and CI status to cards. None of these move a card by themselves (see "Honest scope").
Tool | Method + path | Scopes |
|
|
|
|
|
|
|
|
|
Behavioral notes:
Errors come back as MCP tool errors with the API's own message (the v1 envelope's
messageplus status and machinecode) — e.g.409 wip_limit_reachedwhen 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-2001work anywhere a card is addressed — the v1 API accepts the key as the handle.zuuna_boardpages 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 sayscardsTruncated: trueand carriesnextCursor; send it back ascardsCursorto fetch the next page.zuuna_create_cardaccepts an optional client-chosenidempotencyKey: re-sending the same key after a lost response or a 5xx returns the original card (200) instead of minting a duplicate.zuuna_mealso returns ahiddenToolslist: 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:
Variable | Default | Meaning |
| — (required) | Bearer API token |
|
| Zuuna base URL — must be an absolute http(s) URL (invalid values fail at startup); a plain-http value prints a cleartext-token warning to stderr |
|
| Per-request timeout |
Claude Code
claude mcp add zuuna \
-e ZUUNA_API_TOKEN=zk_live_your_token \
-- npx -y mcp-server-zuunaor in the project's .mcp.json:
{
"mcpServers": {
"zuuna": {
"command": "npx",
"args": ["-y", "mcp-server-zuuna"],
"env": { "ZUUNA_API_TOKEN": "zk_live_your_token" }
}
}
}Cursor
In ~/.cursor/mcp.json (or the project's .cursor/mcp.json):
{
"mcpServers": {
"zuuna": {
"command": "npx",
"args": ["-y", "mcp-server-zuuna"],
"env": { "ZUUNA_API_TOKEN": "zk_live_your_token" }
}
}
}Codex
In ~/.codex/config.toml:
[mcp_servers.zuuna]
command = "npx"
args = ["-y", "mcp-server-zuuna"]
env = { "ZUUNA_API_TOKEN" = "zk_live_your_token" }Run from source
git clone https://github.com/kenzotp/mcp-server-zuuna
cd mcp-server-zuuna && npm install && npm run buildthen point the client at the built binary instead of npx:
claude mcp add zuuna -e ZUUNA_API_TOKEN=zk_live_your_token -- node /path/to/mcp-server-zuuna/dist/index.jsThe loop
zuuna_board— the agent sees the board and picks a card (or you tell it: "do ZNA-2001").The agent codes in your repo with its own tools, referencing the card key in commits.
The PR merges — and git truth moves the card: Zuuna's git integration (webhooks/CLI) links the commits and the PR to the card, and a rule on the board (for example "PR merged → move to Done") moves it. Linking works out of the box; the move is one rule you add once under the board's Automations. After that the agent never has to touch the board by hand, and the board cannot drift from the repository.
Guides
Kanban board for AI agents: the agent sets up the board, writes and moves cards, comments and logs its time; the board's rules carry the cards from there.
Claude Code project management between sessions: a
CLAUDE.mdroutine that keeps an app's plan on the board, so each new session starts where the last one stopped.Zuuna for AI agents: the loop from card to merged PR, in English and German.
Honest scope
There is still no tool that triggers a deploy. zuuna_report_deployment (deployments:write)
only records what a pipeline already did (building, succeeded, failed); actually shipping
stays with your own CI, not the agent.
There are now three git:write tools, and what they do is narrower than the name suggests:
zuuna_record_git_eventsandzuuna_report_ci_checksattach commit/branch/PR history and CI status to whichever card a smart-commit reference or description names.zuuna_link_git_branchesreplaces a repo's whole in-flight-branches snapshot in one call.
None of the three moves a card. A card moves only because a board rule matched it (see
"The loop" above) or because zuuna_move_card / zuuna_update_card was called directly.
Automations themselves stay read-only here too (zuuna_list_automations): no tool creates,
edits or disables one. Attachment uploads go through as multipart (ZNA-2170) with the REST
route's own limits and errors; no tool ever READS a file's bytes back out.
Development
npm install
npm run lint # eslint
npm run build # tsc -> dist/
npm test # vitest, fully mocked (no network)Optional live smoke test, strictly read-only (GET /me and GET /boards only — nothing
is ever created, moved or commented):
ZUUNA_E2E=1 ZUUNA_API_TOKEN=zk_live_your_token npm run test:e2eRequires Node.js >= 20.
License
Available Tools
8 toolszuuna_boardA
Get one board assembled: its columns (in order) and its cards with key, title, column, priority and type. The card list is capped at one 200-card page so a big board cannot flood the context; when more cards exist the response sets cardsTruncated and a nextCursor — pass that as cardsCursor for the next page. Accepts the board id or its key/title (e.g. the card prefix).
Inputs: board (required), cardsCursor.
zuuna_boardsA
List the boards of the token's organization (non-archived, non-private). Each entry carries id, title, card key prefix and timestamps. Use the id with zuuna_board.
Inputs: no named parameters.
zuuna_cardA
Get a card's full detail — description, priority, type, due date, checklist counts, assignees, epic, custom fields, attachments. Accepts the display key (e.g. ZNA-2001) or the card id.
Inputs: card (required).
zuuna_commentA
Add a comment to a card. The author is the user who created the API token. Accepts a card key (ZNA-2001) or id.
Inputs: body (required), card (required).
zuuna_create_cardA
Create a card on a board. Title is required; give the target column by id or by title (omitted = the board's first column). Returns the new card's id and key. Retries are safe: pass the same idempotencyKey again after a lost response or 5xx and the API returns the original card instead of a duplicate.
Inputs: title (required), boardId, boardKey, columnId, +3 more.
zuuna_meA
Show the identity of the Zuuna API token in use: organization, plan, granted scopes and (when lapsed) the grace-window deadline. Use this first to check what the token may do.
Inputs: no named parameters.
zuuna_move_cardA
Move a card to another column. Give the target column by id or by title (resolved against the card's board). Accepts a card key (ZNA-2001) or id.
Inputs: card (required), columnId, columnTitle.
zuuna_update_cardA
Edit a card: title, description and/or priority (HIGHEST|HIGH|NORMAL|LOW|LOWEST, or null to clear). Only the fields you send change. Accepts a card key (ZNA-2001) or id.
Inputs: card (required), title, priority, description.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool maps to a distinct resource+action: token identity, board listing, board detail, card detail, card create, card field update, card move, and card comment. The singular/plural pair (zuuna_board vs zuuna_boards) and explicit verb prefixes (create_, update_, move_) keep boundaries clear, and the only near-overlap (update vs move) is resolved by descriptions that separate field edits from column changes.
All tools share the zuuna_ prefix and snake_case, with bare nouns for reads (zuuna_board, zuuna_card) and verb_noun for writes (zuuna_create_card, zuuna_update_card, zuuna_move_card) — a predictable read/write convention. Minor deviations: zuuna_me doesn't fit the noun/verb_noun pattern, and zuuna_comment omits the explicit action (zuuna_add_comment would match the other writers more closely).
Eight tools is well-scoped for a board/card management server: one identity check, two board-level reads, one card read, and four card mutations. Every tool earns its place, with no redundancy or filler.
The core card workflow is covered (create, read, update title/description/priority, move, comment), but the surface is read-heavy: card detail exposes due dates, assignees, epics, and custom fields that no tool can write, and comments can be added but never retrieved. There is also no delete/archive operation for cards, which is an obvious gap in most card lifecycles.
Maintenance
Related MCP Connectors
Task & board management for AI agents + humans. Kanban, comments, digests via MCP.
Simple kanban for small teams. Read and update your Moxboard boards and tasks from Claude.
Task boards for teams and their AI agents: cards, checklists, sprints, plans and proposals.
Kanban boards your AI agent can use: add, complete, move and recall tasks with your team.
Related MCP Servers
- -licenseNot gradedqualityNot gradedmaintenanceEnables interaction with Azure DevOps Boards through the Model Context Protocol. Supports work item management including listing, updating status, adding comments, and retrieving prioritized cards for development workflows.-

Kanban Zone MCP Serverofficial
AlicenseAqualityCmaintenanceEnables AI assistants to manage Kanban Zone workspaces via 23 tools for boards, cards, comments, checklists, and tasks.2747 npm1MIT- AlicenseNot gradedqualityBmaintenanceEnables AI agents to create, update, list, and delete tasks on a Kanban board via the Model Context Protocol, supporting multi-project management and real-time collaboration.109MIT
- AlicenseBqualityDmaintenanceEnables AI agents to manage kanban boards with tasks, including creating boards, items, moving between columns, and searching.81MIT