KaiBoard MCP

KaiBoard MCP Server

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:

What it does

@kaibuddy/kaiboard-mcp is a single package that serves two combinable modes through the same set of kbfs_* tools:

Both can be enabled at once:

kaiboard-mcp --relay --dir /path/to/workspace

Install

npm install -g @kaibuddy/kaiboard-mcp

or run without installing

npx -y @kaibuddy/kaiboard-mcp

Requires Node.js >= 18.

Connect your MCP client

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:

{

"kaiboard": { "command": "npx", "args": ["-y", "@kaibuddy/kaiboard-mcp", "--relay"], "env": { "KAIBOARD_TOKEN": " " } } }

--relay starts a built-in local relay on 127.0.0.1:8787 that 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):

{

"kaiboard-mcp": { "command": "npx", "args": ["-y", "@kaibuddy/kaiboard-mcp", "--dir", "/path/to/your/workspace"] } }

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

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.

CLI details, envelope format and error codes: see [`docs/PROTOCOL.md`](./docs/PROTOCOL.md).

Elements and fill colors

Elements use the Excalidraw element format. fill is accepted as a shorthand for backgroundColor, and stroke for strokeColor:

{

"type": "rectangle", "id": "r1", "x": 40, "y": 40, "width": 160, "height": 90, "fill": "#ffec99", "stroke": "#e8590c" }

Data and privacy

• Board data is never uploaded to any server. In --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.
• No account, no sign-in.
• On-disk layout (--dir mode): kaiboard-data/boards/ .json plus kaiboard-data/tree.json — a format KaiBoard can open directly.

Development

npm install

npm run typecheck # type check npm run build # build both packages into their dist/ npm run e2e # end-to-end (core + fs adapter / real stdio server) npm run smoke # real MCP client smoke test (initialize -> tools/call)

Third-party notices

Third-party components are referenced as optional peer dependencies (the license text ships inside each package):

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.

Versioning

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.

License

MIT