KaiBoard MCP

KaiBoard MCP 服务

English | 简体中文 · Protocol · Changelog

让支持 MCP 的 AI Agent 在你自己的 KaiBoard 白板上绘图。

KaiBoard 是一款免费、开源、本地优先的白板：你的白板保存在自己的设备上，绝不会存放在云端。 此代码库提供了一个桥接服务，让 Agent 能够读取和编辑这些白板 — Agent 在你的 MCP 客户端运行的任何位置运行，而画布始终留在你的设备上。

其中包含两个可独立使用的软件包：

软件包	作用
@kaibuddy/kaiboard-mcp	MCP 服务（stdio JSON-RPC 2.0），提供 kbfs_* 工具
@kaibuddy/kaiboard-core	与存储无关的命令核心（执行器、元素模型、快照、Mermaid 转换）

---

功能

@kaibuddy/kaiboard-mcp 是一个单一软件包，通过同一组 kbfs_* 工具提供两种可组合模式：

	--relay 模式（推荐）	--dir 模式
后端	正在运行的 KaiBoard 页面	你选择的本地文件夹
应用必须打开吗？	是（并且需在应用中启用“Agent 协同绘图”）	否
典型用途	Agent 在用户正在使用的白板上工作，修改会立即显示	Agent 离线使用并拥有的工作区
数据位置	用户自己的 KaiBoard 库	<folder>/kaiboard-data/

两种模式可以同时启用：

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

安装

npm install -g @kaibuddy/kaiboard-mcp
# or run without installing
npx -y @kaibuddy/kaiboard-mcp

需要 Node.js >= 18。

连接 MCP 客户端

推荐：--relay 模式 — 操作你正在查看的白板，修改会立即显示。 此模式需要中继令牌，可在 KaiBoard 的**“Agent 协同绘图”**面板中获取：

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

--relay 会在 127.0.0.1:8787 上启动内置本地中继，与 KaiBoard 页面通信。 因此，中继和页面必须位于同一台设备上，并且 Agent 工作期间，页面必须保持打开状态。

也可以单独使用 --dir 模式（无需应用 — Agent 在本地文件夹中工作）：

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

或者组合使用："args": ["-y", "@kaibuddy/kaiboard-mcp", "--relay", "--dir", "/path/to/your/workspace"]

修改配置后，请重启 MCP 客户端，以便加载新的服务。

工具

tools/list 返回 20 个工具：19 条命令，加上一项能力声明。 ⚠️ 表示带有 destructiveHint 的工具（可能造成难以撤销的更改）；只读组中的工具均为 readOnlyHint: true。

工具	用途
发现 — 只读
kbfs_list_capabilities	运行时能力：可用命令、存储模式、快照上限、服务信息
kbfs_list_boards	列出画板和文件夹
kbfs_list_trash	列出软删除的画板 / 文件夹（回收站）
kbfs_get_board	读取画板元素
kbfs_get_screenshot	将画板渲染为 PNG，以便 Agent 查看（--relay；在 --dir 下可优雅降级）
画板
kbfs_create_board	创建画板
kbfs_replace_board ⚠️	替换画板内容（自动创建快照）
kbfs_rename_board	重命名画板
kbfs_delete_board ⚠️	删除画板（软删除，可在应用中恢复）
文件夹
kbfs_create_folder	创建文件夹
kbfs_rename_folder	重命名文件夹
kbfs_delete_folder ⚠️	删除文件夹
树结构
kbfs_move_node	将画板或文件夹移入另一个文件夹
kbfs_reorder_node	更改文件夹内的排序
kbfs_restore_node	从回收站恢复画板或文件夹
元素
kbfs_add_element	添加元素
kbfs_patch_element	按 ID 修改元素属性
kbfs_delete_element ⚠️	按 ID 删除元素
内容与元数据
kbfs_from_mermaid	根据 Mermaid 图构建可原生编辑的元素
kbfs_set_metadata	写入画板元数据（状态 / 版本 / 历史 / 评论）

CLI 详情、封装格式和错误代码：参见 docs/PROTOCOL.md。

元素和填充颜色

元素使用 Excalidraw 元素格式。fill 可作为 backgroundColor 的简写，stroke 可作为 strokeColor 的简写：

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

数据与隐私

• 画板数据绝不会上传到任何服务。 在 --relay 模式下，中继仅监听 127.0.0.1，用于同一台机器上的通信；在 --dir 模式下，服务会读取和写入你指定的本地文件夹。
• 无需账户，无需登录。
• 磁盘布局（--dir 模式）：kaiboard-data/boards/<id>.json 加上 kaiboard-data/tree.json — KaiBoard 可直接打开此格式。

开发

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)

第三方声明

第三方组件作为可选的对等依赖项引用（许可证文本随各软件包一同提供）：

组件	许可证	作用
@excalidraw/excalidraw	MIT	元素类型 / 画布渲染（由宿主提供）
@excalidraw/mermaid-to-excalidraw	MIT	Mermaid → 元素转换（可选）

仅用于构建时：typescript（Apache-2.0）、@types/node（MIT）。

未随附任何上游源代码 — 所有组件均作为普通 npm 依赖项使用。

版本管理

当前为 0.4.x — API 在次要版本之间仍可能发生变化。1.0.0 将标志着稳定性承诺。当前版本请参见 CHANGELOG.md。

许可证

MIT