Planban MCP tools reference

Which tools are available by default?

What does each tool take and return?

Every tool except planban_list_boards also needs the board: cwd, the absolute path of a set-up repository, or repoId, a registered board id, used only when cwd is absent. The table lists the other inputs. Tools that change Items accept an optional baseRevision and refuse the change if the board has moved on.

A few rules the tools enforce:

• planban_create_card writes a default Spec when specMarkdown is omitted, and creates a Plan only when planMarkdown is supplied.
• planban_move_card takes parentId: null for the Main Board and afterId: null for the first position. A move to complete requires completionConfirmed: true. A Group cannot be placed inside a Group.
• planban_update_card clears summary, nextAction, blockedBy or metadata when given null, and replaces the whole tag list when given tags.
• planban_write_doc replaces the whole document. With expectedMtimeMs set to the mtimeMs from the last read, it refuses to overwrite a newer file.
• planban_launch_board with demo: true creates or reuses the Planban Demo board. If another program holds the port, it fails with Port 4317 is already in use by another service.

Each tool returns a one-line text summary and the full data as structured content. A change returns the board summary with itemCount and the changed card, rather than every card; planban_get_board remains the full read. A failed call returns an error whose message says what was wrong, such as Card not found: <id>.

What does every result include?

Results that concern one board carry a board link. This covers planban_status for a set-up project, planban_get_board, and every tool that creates or changes Items or documents:

When the URL is verified, userReply.markdown reads [Open the verified board](URL). When it is not, it reads [Open the board](URL) and userReply.verifyWith names planban_launch_board. These results never start the app themselves.

planban_launch_board returns url, urlVerified: true, serviceReady: true, started (whether it started the app or reused a running one), and the same userReply.

Which tools only read?

planban_status, planban_list_boards, planban_get_board, planban_query_cards, planban_get_card and planban_read_doc are marked read-only. The others change a board, except planban_launch_board, which changes no board but can start the local app. No default tool is marked destructive.

How do I enable the administration and recovery tools?

Set PLANBAN_MCP_PROFILE in the MCP server's environment to one or more of these profile names, separated by commas:

planban_delete_board needs confirmRepoId to match repoId exactly. Before it deletes the board's planning state, it copies it to a timestamped backup under ~/.planban/backups/boards/. It never deletes your project repository. These tools match the CLI's board and recovery commands.

What instructions does the server give the agent?

When a host connects, the server sends instructions that every agent receives, with or without the Planban skills. They tell the agent to:

• prefer the Planban tools for all board, card and document reads and writes;
• pass cwd as the absolute repository path, or repoId for a registered board;
• read .planban/agent-context.md before creating or materially editing owner-facing content, and follow the Planban protocol and house style when installed;
• make one change at a time on each board;
• move cards to Complete only when you ask, confirm review or testing, or waive review;
• use planban_move_card for all placement;
• include the exact clickable board URL from userReply.markdown after opening the board or finishing a batch of changes;
• make at most one attempt to show the board in an in-app browser, and never reopen it after every write;
• call planban_launch_board once when boardUrlVerified is false.