KaiBoard MCP server

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": "<your-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 12 tools (11 commands + 1 capability declaration):

CLI details, envelope format and error codes: see 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:

Shortened. The full README is on GitHub.