yctimlin/mcp_excalidraw
MCP server and Claude Code skill for Excalidraw — programmatic canvas toolkit to create, edit, and export diagrams via AI agents with real-time canvas sync.
機能概要
mcp‑excalidraw‑server は、Excalidraw キャンバスをプログラマブルなワークベンチに変え、AI コーディングエージェント（Claude Code、Cursor、Codex CLI など）が操作できるようにします。エージェントは以下のことが可能です：
- 作成・読み取り・更新・削除：JSON コマンドによる個々の図形要素の操作。
- スクリーンショット：ライブキャンバスの取得（現在は Node でヘッドレスにレンダリング、ブラウザ不要）。
- 反復的な図の改善：描画 → 説明 → スクリーンショット → 調整 → 繰り返し。
- エクスポート：コードと一緒にバージョン管理できるネイティブな
.excalidrawファイル（または Obsidian 互換の.excalidraw.md）として結果を出力。 - インポート：Mermaid ダイアグラムのマージ、暗号化 URL の共有、名前付きスナップショットの取得。
これらはすべて、3 つの交換可能なインターフェースを通じて提供されます：
- CLI（
npx -y mcp-excalidraw-server <command>）— エージェントに推奨される方法。 - MCP サーバー — Model Context Protocol（MCP 2026‑07‑28）に対応し、MCP 互換の任意のクライアントで利用可能。
- REST API — LangChain やカスタム HTTP 呼び出し用。
実際の描画はローカルの Node ≥ 20 プロセスで実行され、外部 API キーは不要です。
対象ユーザー
- コーディング支援ツール：開発ワークフローの一環として、アーキテクチャ図、フローチャート、UI モックアップを生成する必要があるもの。
- CI パイプライン：ソースコードの変更時に更新された図を自動レンダリングするもの。
- ドキュメントパイプライン（例：Obsidian ボールト）：視覚アセットをコードと同期させるもの。
- チーム：複数のエージェントが同時に編集できる共有リアルタイムキャンバスを必要とするチーム。
始め方
# ワンライナー：キャンバスを起動して表示（オプション）
npx -y mcp-excalidraw-server start
open http://127.0.0.1:3000 # ブラウザで UI を表示
# JSON で 2 つのボックスと矢印を描画
cat <<EOF | npx -y mcp-excalidraw-server add
[
{"id":"api","type":"rectangle","x":100,"y":100,"width":160,"height":80,"text":"API Server","backgroundColor":"#a5d8ff"},
{"id":"db","type":"rectangle","x":400,"y":100,"width":160,"height":80,"text":"Database","backgroundColor":"#99e9f2"},
{"type":"arrow","startElementId":"api","endElementId":"db","text":"SQL"}
]
EOF
# エージェントに図を確認させ、PNG をキャプチャ
npx -y mcp-excalidraw-server describe
npx -y mcp-excalidraw-server screenshot --out diagram.png
# 図をリポジトリの成果物として保存
npx -y mcp-excalidraw-server export --out docs/arch.excalidraw
同じコマンドは Docker コンテナ内でも、npm ci 後のソースからでも実行できます。
主な機能一覧
| 機能 | 提供されるもの |
|---|---|
| CLI ファースト設計 | すべてのキャンバス操作は合成可能な JSON コマンド。終了コードによりスクリプト化が容易。 |
| MCP 互換性 | 最新の MCP プロトコルを使用して、Claude Desktop、Cursor、Codex CLI、Antigravity などと連携（ハンドシェイク不要）。 |
| ヘッドレスレンダリング | スクリーンショットと画像エクスポートは、jsdom + resvg を使用して Node 内で生成 — 高速、決定的、CI フレンドリー。 |
| 決定的エクスポート | 変更されていないシーンに対してバイト単位で同一の .excalidraw ファイルを生成 → git 差分のノイズなし。 |
| Obsidian サポート | Obsidian Excalidraw プラグイン用に .excalidraw.md へエクスポートし、ブロック参照を保持。 |
| Mermaid インポート | Mermaid テキストをライブな Excalidraw 要素に変換し、既存コンテンツとマージ。 |
| スナップショットシステム | 名前付きの保存/復元ポイントにより、エージェントは図の状態をロールバックまたは分岐可能。 |
| レイアウトツール | 整列、整列、グループ化/グループ解除、ロック、複製 — すべて MCP ツールまたは CLI フラグで実行可能。 |
| 共有 URL | excalidraw.com へのオプションの暗号化アップロードで簡単に共有。 |
| ゼロコンフィグ起動 | 最初の描画コマンドでキャンバスサーバーが自動起動。EXCALIDRAW_NO_AUTOSTART=1 で無効化可能。 |
制限事項 / 注意点
- サーバーはデフォルトで
127.0.0.1にのみバインドされます。外部公開には独自のネットワークファイアウォールが必要です — API に組み込み認証はありません。 - 一部のコマンド（
mermaid変換、--renderer browserによるスクリーンショット）では、実際のブラウザタブを開いておく必要があります。 - Node ≥ 20 が必要です。古いバージョンはサポートされていません。
- フォントは同梱の TTF に限定され、特殊なスクリプトはホスト OS のフォントにフォールバックします。
ライセンスとコミュニティ
- MIT ライセンス — 商用・個人利用ともに無料。
- npm に
mcp-excalidraw-serverとして公開（バッジは現在のバージョンを示します）。 - CI バッジは自動テストと Docker ビルドを示します。
- コントリビューション歓迎。リポジトリには
CONTRIBUTINGスタイルガイドと、ソースからビルドするためのdevelopmentセクションが含まれています。
TL;DR
mcp-excalidraw-server は、ローカルで実行される CLI 駆動の Excalidraw キャンバスで、AI コーディングエージェントが可変の描画サーフェスとして扱えます。要素レベルの CRUD、ヘッドレススクリーンショット、決定的なエクスポート、完全な MCP/REST 統合を提供し、AI ワークフローから直接図を生成、改良、バージョン管理できます。
クイックスタート
# ワンライナー：キャンバスを起動して表示（オプション）
npx -y mcp-excalidraw-server start
open http://127.0.0.1:3000 # ブラウザで UI を表示
# JSON で 2 つのボックスと矢印を描画
cat <<EOF | npx -y mcp-excalidraw-server add
[
{"id":"api","type":"rectangle","x":100,"y":100,"width":160,"height":80,"text":"API Server","backgroundColor":"#a5d8ff"},
{"id":"db","type":"rectangle","x":400,"y":100,"width":160,"height":80,"text":"Database","backgroundColor":"#99e9f2"},
{"type":"arrow","startElementId":"api","endElementId":"db","text":"SQL"}
]
EOF
# エージェントに図を確認させ、PNG をキャプチャ
npx -y mcp-excalidraw-server describe
npx -y mcp-excalidraw-server screenshot --out diagram.png
# 図をリポジトリの成果物として保存
npx -y mcp-excalidraw-server export --out docs/arch.excalidraw
同じコマンドは、Docker コンテナ内または npm ci 後にソースから実行できます。
主な機能一覧
| 機能 | 提供されるもの |
|---|---|
| CLI ファースト設計 | すべてのキャンバス操作は合成可能な JSON コマンド。終了コードによりスクリプト化が容易。 |
| MCP 互換性 | Claude Desktop、Cursor、Codex CLI、Antigravity などと、最新の MCP プロトコル（ハンドシェイク不要）で動作。 |
| ヘッドレスレンダリング | スクリーンショットと画像エクスポートは、Node 内で jsdom + resvg により生成 — 高速、決定的、CI フレンドリー。 |
| 決定的エクスポート | 変更されていないシーンではバイト単位で同一の .excalidraw ファイル → git 差分のノイズなし。 |
| Obsidian サポート | Obsidian Excalidraw プラグイン用に .excalidraw.md へエクスポートし、ブロック参照を保持。 |
| Mermaid インポート | Mermaid テキストをライブな Excalidraw 要素に変換し、既存コンテンツとマージ。 |
| スナップショットシステム | 名前付きの保存/復元ポイントにより、エージェントは図の状態をロールバックまたは分岐できます。 |
| レイアウトツール | 整列、整列、グループ化/グループ解除、ロック、複製 — すべて MCP ツールまたは CLI フラグで実行可能。 |
| 共有 URL | excalidraw.com へのオプションの暗号化アップロードで簡単に共有。 |
| ゼロ設定起動 | 最初の描画コマンドでキャンバスサーバーが自動起動。EXCALIDRAW_NO_AUTOSTART=1 で無効化可能。 |
制限事項 / 注意点
- サーバーはデフォルトで
127.0.0.1にのみバインドされます。外部公開には独自のネットワークファイアウォールが必要です — API には組み込みの認証はありません。 - 一部のコマンド（
mermaid変換、--renderer browserでのスクリーンショット）では、実際のブラウザタブを開いておく必要があります。 - Node ≥ 20 が必要です。古いバージョンはサポートされていません。
- フォントは同梱の TTF に限定され、特殊なスクリプトはホスト OS のフォントにフォールバックします。
ライセンスとコミュニティ
- MIT ライセンス — 商用・個人利用ともに無料。
- npm に
mcp-excalidraw-serverとして公開（バッジは現在のバージョンを示します）。 - CI バッジは自動テストと Docker ビルドを示します。
- コントリビューション歓迎。リポジトリには
CONTRIBUTINGスタイルガイドと、ソースからビルドするためのdevelopmentセクションが含まれています。
TL;DR
mcp-excalidraw-server は、ローカルで実行される CLI 駆動の Excalidraw キャンバスで、AI コーディングエージェントが可変の描画サーフェスとして扱えます。要素レベルの CRUD、ヘッドレススクリーンショット、決定的なエクスポート、完全な MCP/REST 統合を提供し、AI ワークフローから直接図を生成、改善、バージョン管理できます。
クイックスタート
# ワンライナー：キャンバスを起動して表示（オプション）
npx -y mcp-excalidraw-server start
open http://127.0.0.1:3000 # ブラウザで UI を表示
# JSON で 2 つのボックスと矢印を描画
cat <<EOF | npx -y mcp-excalidraw-server add
[
{"id":"api","type":"rectangle","x":100,"y":100,"width":160,"height":80,"text":"API Server","backgroundColor":"#a5d8ff"},
{"id":"db","type":"rectangle","x":400,"y":100,"width":160,"height":80,"text":"Database","backgroundColor":"#99e9f2"},
{"type":"arrow","startElementId":"api","endElementId":"db","text":"SQL"}
]
EOF
# エージェントに図を確認させ、PNG をキャプチャ
npx -y mcp-excalidraw-server describe
npx -y mcp-excalidraw-server screenshot --out diagram.png
# 図をリポジトリの成果物として保存
npx -y mcp-excalidraw-server export --out docs/arch.excalidraw
同じコマンドは、Docker コンテナ内または npm ci 後にソースからも実行できます。
主な機能一覧
| 機能 | 提供されるもの |
|---|---|
| CLI ファースト設計 | すべてのキャンバス操作は合成可能な JSON コマンド。終了コードによりスクリプト化が容易。 |
| MCP 互換性 | 最新の MCP プロトコルを使用して、Claude Desktop、Cursor、Codex CLI、Antigravity などで動作（ハンドシェイク不要）。 |
| ヘッドレスレンダリング | スクリーンショットと画像エクスポートは、Node 内で jsdom + resvg により生成 — 高速、決定的、CI フレンドリー。 |
| 決定的エクスポート | 変更されていないシーンに対してバイト単位で同一の .excalidraw ファイル → git 差分のノイズなし。 |
| Obsidian サポート | Obsidian Excalidraw プラグイン用に .excalidraw.md へエクスポートし、ブロック参照を保持。 |
| Mermaid インポート | Mermaid テキストをライブな Excalidraw 要素に変換し、既存コンテンツとマージ。 |
| スナップショットシステム | 名前付きの保存/復元ポイントにより、エージェントは図の状態をロールバックまたは分岐できます。 |
| レイアウトツール | 整列、整列、グループ化/グループ解除、ロック、複製 — すべて MCP ツールまたは CLI フラグで実行可能。 |
| 共有 URL | オプションで暗号化アップロードを excalidraw.com に行い、簡単に共有。 |
| ゼロコンフィグ起動 | 最初の描画コマンドでキャンバスサーバーが自動起動。EXCALIDRAW_NO_AUTOSTART=1 で無効化可能。 |
制限事項 / 注意点
- サーバーはデフォルトで
127.0.0.1にのみバインドされます。外部に公開するには独自のネットワークファイアウォールが必要です — API には組み込みの認証はありません。 - 一部のコマンド（
mermaid変換、--renderer browserによるスクリーンショット）では、実際のブラウザタブを開いておく必要があります。 - Node ≥ 20 が必要です。古いバージョンはサポートされていません。
- フォントは同梱の TTF に限定され、特殊なスクリプトはホスト OS のフォントにフォールバックします。
ライセンスとコミュニティ
- MIT ライセンス — 商用・個人利用ともに無料。
- npm に
mcp-excalidraw-serverとして公開（バッジは現在のバージョンを示します）。 - CI バッジは自動テストと Docker ビルドを示します。
- コントリビューション歓迎。リポジトリには
CONTRIBUTINGスタイルガイドと、ソースからのビルド手順を含むdevelopmentセクションがあります。
TL;DR
mcp-excalidraw-server は、ローカルで実行される CLI 駆動の Excalidraw キャンバスで、AI コーディングエージェントが可変の描画サーフェスとして扱えます。要素レベルの CRUD、ヘッドレススクリーンショット、決定的なエクスポート、完全な MCP/REST 統合を提供し、AI ワークフローから直接図を生成、改善、バージョン管理することが簡単にできます。
関連
- Dispatch
- プロジェクト
- プロジェクト
- プロジェクト
- プロジェクト