KaiBoard MCP

KaiBoard MCP サーバー

English | 简体中文 · プロトコル · 変更履歴

MCP 対応の AI エージェントが、独自の KaiBoard ホワイトボードに描画できるようにします。

KaiBoard は無料のオープンソースのローカルファーストなホワイトボードです。ボードはお使いのデバイス上に保存され、クラウドには保存されません。 このリポジトリは、エージェントがボードを読み取り、編集するための橋渡しをします。エージェントは MCP クライアントが動作する場所で実行され、キャンバスはお使いのマシン上に保たれます。

このリポジトリには、独立して使用できる 2 つのパッケージが含まれています。

パッケージ	役割
@kaibuddy/kaiboard-mcp	kbfs_* ツールを提供する MCP サーバー（stdio JSON-RPC 2.0）
@kaibuddy/kaiboard-core	ストレージに依存しないコマンドコア（実行機能、要素モデル、スナップショット、Mermaid 変換）

---

できること

@kaibuddy/kaiboard-mcp は、同じ kbfs_* ツールセットを通じて、組み合わせ可能な 2 つのモードを提供する単一のパッケージです。

	--relay モード（推奨）	--dir モード
バックエンド	実行中の KaiBoard ページ	選択したローカルフォルダー
アプリを開く必要があるか	はい（アプリで「エージェントと共同描画」を有効にします）	いいえ
主な用途	エージェントがユーザーの使用中のボードで作業し、変更がすぐに反映されます	エージェントがオフラインで管理するワークスペース
データの保存場所	ユーザー自身の 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 の**「エージェントと共同描画」**パネルから取得するリレートークンが必要です。

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

--relay は、KaiBoard ページと通信する組み込みローカルリレーを 127.0.0.1:8787 上で起動します。 そのため、リレーとページは同じマシン上にある必要があり、エージェントの作業中はページを開いたままにする必要があります。

--dir モードは単独でも使用できます（アプリは不要です。エージェントはローカルフォルダーで作業します）。

{
  "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 個のコマンドと、1 つの機能宣言です。 ⚠️ は destructiveHint ツール（元に戻すのが難しい変更を行う可能性があります）を示します。読み取り専用グループのツールには readOnlyHint: true が設定されています。

ツール	用途
検出 — 読み取り専用
kbfs_list_capabilities	実行時の機能：利用可能なコマンド、ストレージモード、スナップショット上限、サーバー情報
kbfs_list_boards	ボードとフォルダーの一覧表示
kbfs_list_trash	ソフト削除されたボード／フォルダー（ゴミ箱）の一覧表示
kbfs_get_board	ボードの要素を読み取る
kbfs_get_screenshot	エージェントが確認できるようにボードを PNG にレンダリングする（--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