MCP経由のExcalidraw
「Excalidraw MCPを使って」と言うだけで、複雑な図をライブで描画し、適切な場所に保存できます。このスキルがそれを実現します。
すべてを壊すたった一つのこと
create_viewの要素フォーマットはスケルトンであり、ディスク保存用のスキーマではありません。図形のlabelはスケルトン専用の糖衣構文です。Excalidrawのキャンバスレンダラーには、四角形/楕円/ひし形用のテキストブランチがありません。コンテナのテキストはboundElements → containerIdを介してのみ描画されます。そのため、create_viewのJSONを.excalidrawファイルに貼り付けると、空のボックスが静かに生成されます。この単一の事実が、scripts/excalidraw_build.pyが存在する理由です。スケルトンで一度作成すれば、ライブレンダリングと正しいファイルの両方を得られます。
第二の事実:手作業で作成された図は、サイズが大きくなるにつれて徐々に劣化するのではなく、不規則性によって失敗します。実際に生成されたシーンで測定したところ、繰り返しレイアウトの公式で生成された要素の欠陥率は0.00でしたが、特注の単発要素は0.71でした。したがって、公式を使って位置を計算し、リンターで結果をチェックしてください。
新しいマシンでの事前チェック
このスキルをインストールしても、MCPサーバーはインストールされません。mcp-depsはvskill checkが検証する宣言であり、インストーラーではありません。mcp__excalidraw__*ツールが利用できない場合、最初にこれを実行してください。サーバーを検出して登録します。OSを問いません:
python3 scripts/ensure_mcp.py --install
スクリプトはサーバーが見つかった場所を報告するか、claude mcp add --transport http --scope user excalidraw https://mcp.excalidraw.comを実行して再検証します。終了コードは、0:設定済み、1:未検出、2:登録不可(PATHにClaude CLIなし — 手動で実行するコマンドを表示)。Claude Codeは新しく追加されたサーバーを認識するために再起動が必要です。
スコープ:--scope user(デフォルト)は~/.claude.jsonを介してマシン上のすべてのプロジェクトをカバーします。--scope projectは./.mcp.jsonに書き込むため、チームメイトがクローン時に取得できます。--scope localはこのプロジェクトのみです。異なるプロジェクトの下に登録されたサーバーは未検出として扱われます。Claude Codeはここでそれをロードせず、スクリプトもそのように通知します。
MCPがなくても、ライブインラインレンダリングを除くすべての機能は引き続き動作します。
excalidraw_build.pyとexcalidraw_lint.pyはstdlibのみのPython 3です。パッケージもネットワークも不要です。ファイルをビルドし、リンターにかけ、出荷できます。excalidraw_render.pyはさらにpip install playwright && playwright install chromiumが必要です。
Windows
py -3とバックスラッシュを使用してください。Windowsのpython3はMicrosoft Storeのスタブであり、何かを実行する代わりにストアを開きます。
py -3 scripts\ensure_mcp.py --install
py -3 scripts\excalidraw_build.py scene.json -o out.excalidraw
その他はすべてポータブルです。パスはpathlibを通り、出力は明示的なUTF-8と\n改行で書き込まれるため、Windowsの実行でシーンJSONにCRLFが含まれることはなく、事前チェックはclaude.cmd / claude.exeとclaudeの両方を解決します。vskill iがシンボリックリンクが利用できないと警告した場合、コピーにフォールバックします。シンボリックリンクを有効にするには、開発者モードを有効にしてください。
ワークフロー
- 事前チェック(新しいマシンのみ):
mcp__excalidraw__*ツールがない場合、python3 scripts/ensure_mcp.py --installを実行(Windowsではpy -3)。 - スケルトンを作成する。
create_viewが受け付けるのと同じJSON配列を1つ作成します。位置はレイアウト公式(references/layout-recipes.md参照)から計算し、目視で決めてはいけません。 - リンターにかける — オフライン、依存関係なし、オーバーフロー/衝突/ジオメトリをチェック:
python3 scripts/excalidraw_lint.py scene.json --camera--cameraは、上部に貼り付けるための正しくフレーミングされた4:3のcameraUpdateを出力します。 - ライブレンダリングする
mcp__excalidraw__create_viewを使用し、要素をZ順にストリーミング、カメラ移動付き(references/mcp-workflow.md参照)。返されたcheckpointIdを保持します。 - ファイルを保存する ユーザーがディスクに保存したい場合:
python3 scripts/excalidraw_build.py scene.json -o out.excalidraw python3 scripts/excalidraw_build.py scene.json -o out --obsidian # → out.excalidraw.md python3 scripts/excalidraw_build.py scene.json -o out.excalidraw --dark - 確認する 重要なものについては、成功を宣言する前に確認します。これはExcalidraw自身の
exportToSvgを通じてレンダリングするため、テキストは実際のフォントメトリクスで測定されます:
その後、PNGを確認します。見つけた問題を修正し、再リンター、再レンダリングします。python3 scripts/excalidraw_render.py out.excalidraw -o /tmp/preview.png
ステップ2と5が品質ゲートです。これらをスキップすると、ラベルがボックスの外に出たり、矢印が何も指さなくなったりします。
スケルトンチートシート
{"type":"rectangle","id":"api","x":100,"y":80,"width":180,"height":80,
"roundness":{"type":3},"backgroundColor":"#a5d8ff","fillStyle":"solid",
"strokeColor":"#4a9eed","label":{"text":"API Gateway","fontSize":18}}
{"type":"arrow","id":"e1","from":"api","to":"db","label":{"text":"SQL"}} // 自動バインド
{"type":"arrow","id":"e2","from":"api","to":"db","route":"ortho"} // L字
{"type":"arrow","id":"e3","x":300,"y":150,"points":[[0,0],[120,0]]} // 手動
{"type":"text","id":"ttl","center":400,"y":20,"text":"Title","fontSize":24} // 自動中央揃え
{"type":"rectangle","id":"zone","x":40,"y":40,"width":700,"height":420,
"opacity":30,"zoneLabel":"Data layer"} // キャプション、バインドラベルではない
ビルダー専用拡張:from/to(境界アンカー+双方向バインディング)、route:"ortho"、zoneLabel、テキストのcenter、図形のfixedWidth(拡張ではなく折り返し)。その他はすべてそのまま渡されるため、同じ配列をcreate_viewでそのまま使用できます。
背景ゾーンの四角形にバインドされたlabelを決して置かないでください。ゾーンの中央に配置され、掴めなくなります。代わりにzoneLabelを使用してください。
出力の選択
| 出力先 | コマンド | メモ |
|---|---|---|
| 今すぐユーザーに表示 | create_view | アニメーション表示、カメラガイド付き。checkpointIdを返す |
| リポジトリ内のファイル | excalidraw_build.py -o x.excalidraw | excalidraw.comまたはVS Code拡張機能で開く |
| Obsidianボールト | ... -o x --obsidian | .excalidraw.md、プラグイン解析可能、git差分可能 |
| 共有可能なリンク | mcp__excalidraw__export_to_excalidraw | excalidraw.comにアップロード — 事前に確認すること |
MCPにはローカルファイルツールはありません。export_to_excalidrawは公開アップロードです。公開として扱い、呼び出す前にユーザーに確認してください。
イテレーション
create_viewはcheckpointIdを返します。その状態から続行するには — フルスクリーンでのユーザー編集を含む — 次の配列を{"type":"restoreCheckpoint","id":"<checkpointId>"}で開始し、新しいものだけを追加します。{"type":"delete","ids":"a,b"}を使用して要素を削除します。削除されたIDを再利用しないでください。ディスク上のスケルトンファイルは同期を保ってください。そのファイルがビルドとリンターの対象となるためです。
参考文献
references/file-format.md— ディスク保存用スキーマ、アップストリームに対して検証済み:フォントコード、バインドテキスト、矢印ジオメトリ、バインディング、Excalidrawが開くときに再計算するものとしないもの。.excalidrawファイルを手動編集する前に読むこと。references/mcp-workflow.md— カメラの動き、ストリーミング順序、チェックポイント、ダークモード、MCP自身の制限。references/layout-recipes.md— フロー、階層化、スイムレーン、シーケンス、グリッド、放射状、マトリックスレイアウトの公式と、60要素の図を読みやすく保つ方法。references/obsidian.md—.excalidraw.mdラッパー、ブロック参照ルール、圧縮シーンの落とし穴。scripts/ensure_mcp.py— 任意のOSでExcalidraw MCPサーバーを検出して登録。scripts/split_excalidraw_library.py—.excalidrawlib(libraries.excalidraw.comのAWS/GCP/K8sアイコンパック)をアイコンごとのJSONとルックアップテーブルに分割。アイコンデータがコンテキストに入るのを防ぎます。
明確にしておくべき制限
- 幅の推定はフォントバイナリから測定されたものではなく、文字ごとに調整されています。リンターはオーバーフローの10%以内で警告します。重要なもので警告が出た場合はレンダリングしてください。
excalidraw_render.pyはplaywrightとesm.shへのネットワークアクセスが必要です。これらがない場合でも、リンターは完全にオフラインで動作します。- リンターは図が良いかどうかを判断できず、正しいかどうかのみを判断します。構成は依然としてあなたの仕事です。
変更履歴
- 1.2.0 —
scripts/ensure_mcp.py:クロスプラットフォームの事前チェック。MCPサーバー(~/.claude.jsonのプロジェクトごとのマップを含む)を検出し、欠落している場合は登録。Windowsサポート:py -3、claude.cmdの解決、すべての書き込みで明示的なUTF-8と\n改行を文書化。 - 1.1.1 — リンターはボックスフィットルール(R1/R2)を矢印コンテナに適用しなくなりました。矢印ラベルはパスに沿って配置され、R10でカバーされます。
- 1.1.0 —
skills/excalidraw-mcp/のvskillモノレポに移動。remotion-best-practicesや他のリポジトリ内スキルと一致。スタンドアロンのanton-abyzov/excalidraw-mcp-skillリポジトリは非推奨。 - 1.0.1 — MCPセットアップを文書化:スキルのインストールはサーバーをインストールしない。
claude mcp addのワンライナーと、それがなくても動作するものを追記。 - 1.0.0 — 初回リリース。ファイル専用の
excalidraw-diagram-generatorスキルを置き換え。そのテンプレートは図形にインラインtextを出力していたため、空のボックスとして開かれていた。