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 など) が操作できるプログラマブルなワークベンチに変えます。キャンバスは完全にローカルで動作し (Node ≥ 20、API キー不要)、次の 3 つの方法でアクセスできます。
- CLI –
npx -y mcp-excalidraw-server <command>– キャンバスを自動起動し、要素の追加・更新・削除、スクリーンショットの取得、ファイルのエクスポートなどを行う JSON ベースのコマンド群。 - MCP サーバー – 26 のツールを公開する Model Context Protocol (MCP) の stdio サーバー。MCP 対応クライアントから描画操作を直接呼び出せます。
- REST API – LangChain などのフレームワーク向けのプレーンな HTTP/WebSocket エンドポイント。
結果として得られるのは、エージェントが (describe やスクリーンショットで) 検査し、要素ごとに修正を加え、最後に .excalidraw ファイルとしてエクスポートできる、ライブで編集可能なダイアグラムです。このファイルはソースコードの隣や Obsidian ボールトに置けます。
誰のためのものか
- コーディングアシスタント – 開発ワークフローの一部として、アーキテクチャ図、フローチャート、UI モックアップを生成する必要があるもの。
- チーム – ダイアグラムファイルをコードと一緒にバージョン管理したい (例:
.excalidrawファイルを Git にコミットする) チーム。 - Obsidian ユーザー – ダイアグラムをボールトに保存し、完全な編集可能性を維持したいユーザー。
- カスタム AI エージェントツールチェーンを構築する人 – MCP ツールや REST API を呼び出せるツールチェーンを構築する開発者。
主な機能 (README より)
| 機能 | 説明 |
|---|---|
| ローカルキャンバスサーバー | http://127.0.0.1:3000 で Excalidraw Web UI を実行し、リアルタイムの WebSocket 同期を提供。外部サービスは不要。 |
| CLI ファーストの設計 | すべての機能が合成可能なコマンド (add、apply、query、screenshot、export、mermaid、snapshot、arrange、share など) として公開。JSON を標準出力に出力し、終了コードで成功/失敗を示します。 |
| MCP 統合 | MCP プロトコルリビジョン 2026-07-28 を実装。26 のツールにより、あらゆる MCP クライアント (Claude Desktop、Cursor、Codex CLI、Antigravity など) が stdio 経由でキャンバスを操作できます。 |
| REST API | LangChain やカスタムスクリプト向けのシンプルな HTTP エンドポイント。 |
| 要素レベルの CRUD | 個々の図形、矢印、テキスト、グループ、ロックなどを作成、読み取り、更新、削除できます。 |
| 反復的な改良 | エージェントは describe でシーンを確認し、screenshot を撮り、レイアウトを調整して、ダイアグラムが完成するまで繰り返せます。 |
| エクスポート / インポート | ネイティブの .excalidraw JSON、または Obsidian 互換の .excalidraw.md にエクスポート。圧縮ファイルを含む両形式のインポートに対応。 |
| 決定論的なエクスポート | ID、シード、キーの順序が安定しているため、変更のないダイアグラムは同一のファイルを生成し、ノイズの多い Git 差分が発生しません。 |
| Mermaid 変換 | Mermaid 構文を貼り付けると、生成されたダイアグラムが既存のキャンバスにマージされます。 |
| ビューポート制御 | 選択した要素へのズーム、パン、フィットのコマンド。 |
| 共有 | オプションで暗号化されたアップロードを excalidraw.com に行い、共有可能な URL を生成します。 |
| Docker イメージ | 簡単なデプロイのためのプリビルドコンテナ (ghcr.io/yctimlin/mcp_excalidraw)。 |
| エージェントスキルバンドル | ポータブルなスキル (skills/excalidraw-skill/) で、単一の install-skill コマンドでエージェントのスキルディレクトリにインストールできます。 |
| ゼロセットアップの自動起動 | CLI コマンドと MCP サーバーは、キャンバスが実行されていない場合に自動的に起動します (EXCALIDRAW_NO_AUTOSTART=1 で無効化)。 |
クイックスタート
# インストールしてキャンバスを起動 (最初の描画コマンドで自動起動)
npx -y mcp-excalidraw-server start
open http://127.0.0.1:3000 # 任意 – スクリーンショットや Mermaid に必要
# 2 つのボックスと矢印を追加 (JSON を標準入力で渡す)
echo '[
{"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"}
]' | npx -y mcp-excalidraw-server add
# エージェントにダイアグラムを見せる
npx -y mcp-excalidraw-server describe
npx -y mcp-excalidraw-server screenshot --out diagram.png
# バージョン管理用にエクスポート
npx -y mcp-excalidraw-server export --out docs/architecture.excalidraw
同じコマンドは、MCP 対応クライアントから、または HTTP 経由でも呼び出せます。
既知の制限 / 未解決の問題 (README より)
- サーバーはデフォルトで
127.0.0.1にのみバインドされます。外部からアクセスするには、ユーザー自身がファイアウォールやリバースプロキシを設定する必要があります – 組み込みの認証はありません。 - 一部の操作 (例:
screenshot、mermaid変換) では、クライアント側の Excalidraw UI に依存するため、ブラウザのタブを開いておく必要があります。 - README には「既知の問題 / TODO」セクションがいくつかありますが、具体的なバグは列挙されていません。最新の状況はイシュートラッカーを確認してください。
メンテナー
このリポジトリは yctimlin が所有し、npm に mcp-excalidraw-server として公開されています (MIT ライセンス)。継続的インテグレーションは、プッシュのたびにテストを実行し、Docker イメージをビルドします。
TL;DR
mcp-excalidraw-server は、AI コーディングエージェントに、プログラムで制御できる実際に編集可能な描画サーフェスを提供します。シンプルな CLI、MCP stdio サーバー、または REST API を介して動作し、ダイアグラムをバージョン管理された .excalidraw ファイルとして保存します。これにより、LLM が生成したアーキテクチャのアイデアと、具体的で編集可能なダイアグラムの間の実用的な橋渡しを実現します。
関連
- プロジェクト
- プロジェクト
- プロジェクト
- プロジェクト
- プロジェクト