KaiBoard MCP

io.github.ChasenKaiPublished by GitHub account ChasenKaiv0.4.2Updated Oct 25, 2026

Let AI agents draw on your local-first KaiBoard whiteboards (relay or local folder).

VerifiedSTDIODesktop onlyProductivity & WorkflowFiles & Storage

Overview

AI-generated overview

A local MCP server that lets an AI assistant read and edit your own KaiBoard whiteboards, either on a live board through a local relay or in a local folder.

What you can do
List boards, folders and trash, read a board's elements, and render a board to PNG for viewing (relay mode). Create, rename, replace and soft-delete boards, and create, rename and delete folders. Move, reorder and restore boards or folders in the tree. Add, patch and delete individual elements on a board. Build editable elements from a Mermaid diagram and write board metadata such as status, version, history and comments.
When to use it
Use it when you keep whiteboards in the local-first KaiBoard app and want an assistant to sketch, diagram or reorganize them. Relay mode suits working on the board you are looking at; folder mode suits an offline workspace the agent owns.
Requirements
Node.js 18 or newer, run locally over stdio via npx or a global npm install. Relay mode needs the KaiBoard app open on the same machine with Agent co-draw enabled, plus a relay token in the KAIBOARD_TOKEN environment variable; it starts a local relay on 127.0.0.1:8787. Folder mode needs only a writable directory path.
Before you install
Relay mode requires the KAIBOARD_TOKEN secret, which grants access to your live board; keep it out of shared configs. Several tools are marked destructive: replacing a board's contents, deleting boards or folders, and deleting elements. Board deletion is a soft delete restorable in the app, and board replacement takes an automatic snapshot, but element deletion and folder deletion may be hard to undo. The API is pre-1.0 and may change between minor versions.

Installation

In SourceWeft

  1. Open KaiBoard MCP in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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.

[Request flow: an MCP client sends kbfs_* tool calls over stdio JSON-RPC to kaiboard-mcp; from there it reaches KaiBoard either through the built-in local relay on 127.0.0.1 (driving the page you have open) or by reading and writing a local folder you choose. No account, no sign-in, and board data is never uploaded to a server.]

It contains two independently usable packages:

PackageRole
@kaibuddy/kaiboard-mcpMCP server (stdio JSON-RPC 2.0) exposing the kbfs_* tools
@kaibuddy/kaiboard-coreStorage-agnostic command core (executor, element model, snapshots, Mermaid conversion)

What it does

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

--relay mode (recommended)--dir mode
BackendA running KaiBoard pageA local folder you choose
App must be open?Yes (with "Agent co-draw" enabled in the app)No
Typical useThe agent works on the user's live board, changes visible immediatelyA workspace the agent owns offline
Data locationThe user's own KaiBoard library<folder>/kaiboard-data/

Both can be enabled at once:

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

Install

bash
npm install -g @kaibuddy/kaiboard-mcp# or run without installingnpx -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:

json
{  "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):

json
{  "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.

ToolPurpose
Discovery — read-only
kbfs_list_capabilitiesRuntime capabilities: available commands, storage modes, snapshot limit, server info
kbfs_list_boardsList boards and folders
kbfs_list_trashList soft-deleted boards / folders (trash)
kbfs_get_boardRead a board's elements
kbfs_get_screenshotRender a board to PNG so the agent can look at it (--relay; degrades gracefully under --dir)
Boards
kbfs_create_boardCreate a board
kbfs_replace_board ⚠️Replace a board's contents (auto-snapshot)
kbfs_rename_boardRename a board
kbfs_delete_board ⚠️Delete a board (soft delete, restorable in the app)
Folders
kbfs_create_folderCreate a folder
kbfs_rename_folderRename a folder
kbfs_delete_folder ⚠️Delete a folder
Tree
kbfs_move_nodeMove a board or folder into another folder
kbfs_reorder_nodeChange ordering within a folder
kbfs_restore_nodeRestore a board or folder from the trash
Elements
kbfs_add_elementAdd elements
kbfs_patch_elementPatch element properties by id
kbfs_delete_element ⚠️Delete elements by id
Content & metadata
kbfs_from_mermaidBuild native editable elements from a Mermaid diagram
kbfs_set_metadataWrite board metadata (status / version / history / comments)

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:

json
{  "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/<id>.json plus kaiboard-data/tree.json — a format KaiBoard can open directly.

Development

bash
npm installnpm run typecheck   # type checknpm 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):

ComponentLicenseRole
@excalidraw/excalidrawMITelement types / canvas rendering (provided by the host)
@excalidraw/mermaid-to-excalidrawMITMermaid → 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.

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

Source: README.md at commit 0d8f940

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

3
  1. v0.4.2LatestSep 28, 2026
  2. v0.2.0Sep 18, 2026
  3. v0.1.0Sep 17, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts