MCP Server Zuuna

Create up to 50 cards on ONE board in a single call. Each item validates exactly like zuuna_create_card (title required; target column by id only) and the answer is one result per item: created (id, key, title, status, columnId) or the error that item alone would have gotten. The card cap counts the whole batch; board, closed-sprint and limit errors stay whole-request.

Add a column to an existing (non-archived) board.

Create an epic in a group: a real ticket with its own key (a board-less group card), referencable and linkable like any other card. Title is required; colour comes from the 8-name palette and defaults to purple.

Start a recurring-card series on a board: every everyN unit(s) (days|weeks|months) it mints a card from the given template, until endAt (if set).

Plan or publish a release in a group. Provide releaseId (to fill in an existing planned release), or a name/tag to create one. publish defaults to false when no tag/commits context is given — pass publish: true to mark it RELEASED and fire release.published to webhook subscribers immediately.

Create a PLANNED sprint in a group.

Register a webhook endpoint. The response's `secret` is the ONLY time the signing secret is ever shown — store it immediately, there is no way to read it back.

Remove an attachment from a card. Requires confirm: true.

Move a card to Trash (restorable for 30 days via zuuna_restore_card, then permanently purged). Refused with time_entries_exist if the card carries logged time, UNLESS confirm is true — passing confirm also acknowledges deleting those hours. Requires confirm: true.

Remove a checklist item. Requires confirm: true.

Cancel a recurring-card series for good (no trash). Requires confirm: true.

Remove a relation, from either card it connects. Requires confirm: true.

Permanently delete a release (its commit/merge history, sprint links, card-release links and shipped-card archive all cascade with it). Requires confirm: true.

Remove a logged time entry. Requires confirm: true.

Remove a webhook endpoint (its delivery log goes with it). Requires confirm: true.

Get one attachment's metadata (filename, MIME type, byte size). Never returns the file's bytes — use zuuna_list_attachments first to find the attachmentId.

Get one release's detail: state, dates, tag, shipped card/point counts.

Get a sprint plus the cards currently in it.

Bulk-import normalized time entries (up to 200 per call) — from Clockify/Toggl/Harvest or a script. Each entry needs cardKey/cardId (or a PREFIX-N in description) plus seconds or start+end; userEmail attributes it. Idempotent on (source, externalId): repeating one updates it rather than duplicating it. One bad entry does not fail the rest.

REPLACE-ALL snapshot of a repo's in-flight branches in a group (up to 500). Each needs at least name and headSha; a branch named for a card ("ZNA-249-…" or matching the group's prefix) links automatically. An empty branches array is refused unless confirmEmpty is true — that guard exists so a half-failed snapshot cannot silently wipe the page.

List every running timer visible to this token, optionally filtered to one member by email.

List a card's attachments (metadata only: id, filename, MIME type, size, who uploaded it).

Read a board's automation rules: trigger, conditions, actions, enabled, recent run outcomes. Read-only — automations cannot be created or edited through this server, only inspected. A sendWebhook action's URL is redacted (it can carry a chat-app incoming-webhook secret).

List a board's cards, in board order by default (column then position). `archived` narrows to false|true|all (default false); `updatedSince` (ISO 8601) narrows to cards changed after it, for incremental sync.

Read the custom fields attached to a board: id, name, type, in display order. For SELECT, MULTISELECT and TAGS fields, options is the option vocabulary a card's customFields value may use; for every other type options is null. update_card's customFields argument is keyed by these field ids.

List logged time entries on a card, newest first, plus the card's total seconds.

Read a card's checklist: every item plus the total/completed counts the card face shows.

List a board's columns in order — id, title, isDone, statusCategory, position, WIP limit, SLA hours. These columnId values are what a card move expects.

Read a card's discussion, oldest first — the order it happened, and the order an incremental sync appends in.

List deployment history, optionally narrowed to a group and/or environment.

List a group's epics — id, key, title, colour. An epic is a real card (Prisma model Label; the UI calls it an Epic), so its key resolves through the ordinary card tools too.

List every card in a group, whether it stands on a board or in the group's backlog (a board-less card, columnId null). Use this to discover backlog cards — no other list surfaces them. `placement` narrows to board|backlog|all (default all).

List a group's members: id, name, email. These ids are the valid values for a card's assigneeIds.

List the workspace's groups (Prisma model Team; the UI calls this a Group — it owns boards, sprints, releases and the card-key prefix). A restricted group this token may not act in is omitted, not merely flagged. The returned id is what every groupId argument elsewhere expects.

List a board's recurring-card series, paused and active both.

List a card's relations to other cards (blocks, depends on, subtask of, scheduling links, ...), each with its direction relative to this card.

List a group's releases, optionally narrowed to a state (PLANNED|RELEASED|ARCHIVED).

List the workspace's sprints, optionally narrowed to one group and/or state (PLANNED|ACTIVE|CLOSED).

Read an endpoint's last 20 delivery attempts (payload truncated to 2 KB; a payload naming a board this token cannot read is redacted).

List this workspace's webhook endpoints. Never returns a signing secret (only the create call does, once).

Log a CLOSED time entry on a card — work already done. Provide seconds or a duration string ("2h 30m"). For an ongoing timer use zuuna_start_timer / zuuna_stop_timer instead.

Show the identity of the Zuuna API token in use: organization, plan, granted scopes and — only when the workspace's subscription has lapsed — the grace-window deadline after which every call here will start failing. Also lists, as hiddenTools, every tool this token's scopes hide, each with the scope(s) that would unlock it. Call this first to learn what this token may do; a tool absent from the tool list this session means its scope was not granted.

Move a card to another column on the SAME board. Give the target column by id or by title (resolved against the card's own board). For moving to a DIFFERENT board use zuuna_move_card_to_board.

Move a card to a DIFFERENT board (cross-board move). Optional targetColumnId; omitted, the card lands in the target's default column for its current status category.

Record git events (commit/branch/pr, up to 1000 per call) via smart-commits ("PREFIX-123" in the ref or message) to link them to cards.

Take a card out of its sprint (clears its sprint membership). A card standing on the sprint's OWN materialized board leaves it for the group's backlog; a card on an ordinary board stays exactly where it is.

Record CI status checks (up to 1000 per call), each attached to whichever card its commit/branch/PR or description names.

Report a deployment's progress (building|succeeded|failed|...) or update the one in flight. Idempotent on (environment, externalId) — repeat callbacks from the same CI run update ONE row. groupId binds it to a release/board pipeline; omitted, it is still recorded workspace-wide.

Pull a card back out of Trash. Refused if the workspace is at its card limit (an archived+trashed card is exempt).

Search cards workspace-wide: the one list that needs no board or group id up front. Filters narrow: q (case-insensitive text in title + description), groupId, boardId, columnId, assigneeId, epicId, priority (HIGHEST|HIGH|NORMAL|LOW|LOWEST), label (a tag option id or "<fieldId>:<optionId>" token). archived narrows to false|true|all (default false); updatedSince (ISO 8601) narrows to cards changed after it, for incremental sync. Bad values are refused with an error, never silently ignored.

Start a running timer on a card. Idempotent: starting an already-running timer for the same person is a no-op, not an error. Optional userEmail delegates the timer to another workspace member (e.g. relaying a Slack action) — resolved against THIS workspace's membership only.

Stop a card's running timer, closing it at the elapsed duration. A no-op (not an error) if nothing is running.

Send a real `ping` delivery to one endpoint, regardless of its subscribed events, and report the fresh delivery status.

Restore an archived card to active (the inverse of zuuna_archive_card). Refused if the workspace is at its card limit.

Edit a card. Only the fields you send change: title, description, priority, type, dueDate, startDate, estimateSeconds, storyPoints, ready, columnId (move within the SAME board — a cross-board move is zuuna_move_card_to_board), assigneeIds (REPLACES the full set; [] clears everyone), customFields (object keyed by field id; null/empty clears one — zuuna_list_board_fields names the ids and the option vocabulary).

Rename and/or tick a checklist item. Only the fields you send change.

Edit an epic. Only the fields you send change: title, description, colour.

Edit a series' interval, end date and/or pause state (enabled). Resuming a paused series re-schedules its next run from now, so it never bursts out catch-up cards.

Correct a release. action=edit changes name/description/releaseDate/notes/tag (only the fields you send); unpublish reverts a RELEASED release to PLANNED (keeps its shipped-card archive); archive/unarchive is a display filter, not a data lock.

Update a sprint's name/goal/dates. Only the fields you send change. Sprint lifecycle (start/close) is not exposed here — it materializes boards and archival metrics and stays an in-app action.

Correct a logged time entry's duration and/or note. Refused while the entry's timer is still running — stop it first.

Edit a webhook endpoint. Only the fields you send change; enabled: false is how a subscriber pauses itself without losing the registration.

Upload a file onto a card from a local file path, or from base64 plus a filename. The same limits the REST upload route enforces apply and its errors surface verbatim: 10 MB per file, the workspace storage cap (409 limit_reached), executable extensions refused, and the token creator needs a verified email.