The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the KaiBoard MCP listing page.
English | 简体中文 · Protocol · Changelog
Let MCP-capable AI agents draw on your own KaiBoard whiteboards.
KaiBoard is a free, open-source, local-first whiteboard: your boards live on your own device, never in the cloud. This repo is the bridge that lets an agent read and edit those boards — the agent runs wherever your MCP client runs, and the canvas stays on your machine.
It contains two independently usable packages:
| Package | Role |
|---|---|
@kaibuddy/kaiboard-mcp | MCP server (stdio JSON-RPC 2.0) exposing the kbfs_* tools |
@kaibuddy/kaiboard-core | Storage-agnostic command core (executor, element model, snapshots, Mermaid conversion) |
@kaibuddy/kaiboard-mcp is a single package that serves two combinable modes through the same set of kbfs_* tools:
--relay mode (recommended) | --dir mode | |
|---|---|---|
| Backend | A running KaiBoard page | A local folder you choose |
| App must be open? | Yes (with "Agent co-draw" enabled in the app) | No |
| Typical use | The agent works on the user's live board, changes visible immediately | A workspace the agent owns offline |
| Data location | The user's own KaiBoard library | <folder>/kaiboard-data/ |
Both can be enabled at once:
Requires Node.js >= 18.
Recommended: --relay mode — drives the board you're looking at, with changes visible immediately.
It needs a relay token, obtained from KaiBoard's "Agent co-draw" panel:
--relaystarts a built-in local relay on127.0.0.1:8787that talks to the KaiBoard page. The relay and the page must therefore be on the same machine, and the page has to stay open while the agent works.
--dir mode can also be used on its own (no app required — the agent works in a local folder):
Or combine them: "args": ["-y", "@kaibuddy/kaiboard-mcp", "--relay", "--dir", "/path/to/your/workspace"]
Restart your MCP client after changing the config so it picks up the new server.
tools/list returns 20 tools: 19 commands plus one capability declaration.
⚠️ marks a destructiveHint tool (may make hard-to-undo changes); the tools in the
read-only group are readOnlyHint: true.
| Tool | Purpose |
|---|---|
| Discovery — read-only | |
kbfs_list_capabilities | Runtime capabilities: available commands, storage modes, snapshot limit, server info |
kbfs_list_boards | List boards and folders |
kbfs_list_trash | List soft-deleted boards / folders (trash) |
kbfs_get_board | Read a board's elements |
kbfs_get_screenshot | Render a board to PNG so the agent can look at it (--relay; degrades gracefully under --dir) |
| Boards | |
kbfs_create_board | Create a board |
kbfs_replace_board ⚠️ | Replace a board's contents (auto-snapshot) |
kbfs_rename_board | Rename a board |
kbfs_delete_board ⚠️ | Delete a board (soft delete, restorable in the app) |
| Folders | |
kbfs_create_folder | Create a folder |
kbfs_rename_folder | Rename a folder |
kbfs_delete_folder ⚠️ | Delete a folder |
| Tree | |
kbfs_move_node | Move a board or folder into another folder |
kbfs_reorder_node | Change ordering within a folder |
kbfs_restore_node | Restore a board or folder from the trash |
| Elements | |
kbfs_add_element | Add elements |
kbfs_patch_element | Patch element properties by id |
kbfs_delete_element ⚠️ | Delete elements by id |
| Content & metadata | |
kbfs_from_mermaid | Build native editable elements from a Mermaid diagram |
kbfs_set_metadata | Write board metadata (status / version / history / comments) |
CLI details, envelope format and error codes: see docs/PROTOCOL.md.
Elements use the Excalidraw element format. fill is accepted as a shorthand for backgroundColor, and stroke for strokeColor:
--relay mode the relay listens on 127.0.0.1 only, for same-machine communication; in --dir mode the server reads and writes the local folder you specify.--dir mode): kaiboard-data/boards/<id>.json plus kaiboard-data/tree.json — a format KaiBoard can open directly.Third-party components are referenced as optional peer dependencies (the license text ships inside each package):
| Component | License | Role |
|---|---|---|
@excalidraw/excalidraw | MIT | element types / canvas rendering (provided by the host) |
@excalidraw/mermaid-to-excalidraw | MIT | Mermaid → element conversion (optional) |
Build-time only: typescript (Apache-2.0), @types/node (MIT).
No upstream source code is vendored — every component is used as an ordinary npm dependency.
Currently 0.4.x — the API may still change between minor versions. 1.0.0 will mark the stability commitment. See CHANGELOG.md for the current release.