Excalidraw MCP連携で実現するAI図解自動生成の全体像と導入前に知るべき前提条件

Excalidraw MCP連携で実現するAI図解自動生成の全体像と導入前に知るべき前提条件

Excalidraw MCP連携とは、Anthropicが策定したModel Context Protocol（MCP）を介して、ClaudeなどのAIエージェントからExcalidrawの描画機能を直接操作できる仕組みです。従来、AIに図を描かせるにはMermaid記法やPlantUMLのテキストベース出力に頼るしかありませんでしたが、MCP連携によってリアルタイムにキャンバス上へ手書き風のダイアグラムを生成・編集できるようになりました。このセクションでは、AI図解自動生成の全体構造と、導入前に押さえておくべき技術要件を整理します。

MCPを介したAI図解生成の仕組みとExcalidrawが選ばれる3つの技術的理由

MCP（Model Context Protocol）は、AIモデルと外部ツールをつなぐ標準プロトコルとして2024年11月にAnthropicが発表したオープン仕様です。AIエージェントがMCPサーバーに対して「矩形を座標(100,100)に幅300で配置せよ」といった構造化リクエストを送ると、MCPサーバーがExcalidrawのAPI経由でキャンバス上に即座に要素を描画します。人間が自然言語で「ユーザーからAPIサーバーを経由してデータベースにつながるアーキテクチャ図を描いて」と指示するだけで、AIがMCPツールを呼び出し、要素の配置・接続・テキスト挿入を自動で行う流れです。

Excalidrawが図解ツールとして選ばれる技術的理由は主に3つあります。第一に、手書き風レンダリングによる視覚的な柔らかさです。設計レビューやプレゼンテーションで「完成品ではなく検討中のドラフト」という印象を与えやすく、フィードバックを得やすい特性があります。第二に、JSON形式によるデータ構造のシンプルさです。各要素がtype・座標・サイズ・テキストなどのプロパティで構成されており、AIが生成・解析しやすい形式になっています。第三に、オープンソースかつブラウザベースで動作するため、ローカル環境へのセルフホストが容易で、社内ネットワーク内での利用にも対応できる点が挙げられます。

CanvasサーバーとMCPサーバーの2プロセス構成を理解するための役割分担図

Excalidraw MCP連携（コミュニティ版mcp_excalidraw）は、CanvasサーバーとMCPサーバーという2つの独立したプロセスで動作します。Canvasサーバーはデフォルトでhttp://localhost:3000にホストされ、ブラウザ上にExcalidrawのWeb UIを表示するとともに、REST APIとWebSocketによるリアルタイム更新機能を提供します。一方、MCPサーバーはstdio（標準入出力）経由でClaude DesktopやCursorなどのMCPクライアントと通信し、受け取った指示をEXPRESS_SERVER_URLで指定したCanvasサーバーのAPIに転送する役割を担います。

この2プロセス構成のメリットは、描画結果をブラウザで即座に目視確認できる点にあります。AIエージェントが要素を作成するたびにWebSocket経由でCanvasサーバーに変更が通知され、ブラウザ上のExcalidrawキャンバスがリアルタイムに更新されます。つまり、AIが「描いている最中」の過程をライブで確認しながら、必要に応じて追加指示を出せるワークフローが実現します。公式版MCPはチャット内にインライン描画する方式のため、この2プロセス構成はコミュニティ版特有のアーキテクチャです。

導入前に確認すべきNode.jsバージョンとnpmビルド環境の最低要件

Excalidraw MCPサーバー（コミュニティ版mcp_excalidraw）を導入する際の最低要件は、Node.js 18以上とnpmが利用可能な環境です。2026年2月時点ではNode.js v24系での動作も確認されていますが、LTS版であるNode.js 20系を推奨します。npmについてはv9以上であれば問題なく、npm ciコマンドでlockfileに基づいた厳密なインストールが行われます。ビルドはnpm run buildでTypeScriptのトランスパイルが実行され、dist/index.jsが生成されれば準備完了です。

確認手順としては、ターミナルでnode -vとnpm -vを実行してバージョンを確かめた後、リポジトリのクローンとビルドを行い、ls -l dist/index.jsでファイルの存在を確認するのが確実です。macOS・Windows・Linuxのいずれでも動作しますが、パス指定に絶対パスを使用する必要がある点に注意してください。GitHubのREADMEに記載されている/absolute/path/to/という文字列をそのまま設定ファイルにコピーしてしまい、起動エラーになるケースが報告されています。

Mermaid記法やMarkdown図解との違いから見るMCP連携の実務的メリット

Mermaid記法はテキストベースで図を定義するため、AIが生成するトークン数が少なく、GitHubやGitLabのMarkdownプレビューでそのまま表示できる利便性があります。しかし、レイアウトの自由度が低く、要素の配置位置やサイズを細かく制御することが困難です。複雑なアーキテクチャ図やワイヤーフレームでは、Mermaidの自動レイアウトが意図しない配置になることも少なくありません。

Excalidraw MCP連携の実務的メリットは、座標レベルでの精密な配置制御と、生成後の反復的な改善が可能な点にあります。AIがcreate_elementで矩形やテキストを配置し、describe_sceneで現在の配置状況を確認し、update_elementで位置やサイズを微調整するという閉ループの改善プロセスを実行できます。Mermaidが「一度きりの生成」であるのに対し、Excalidraw MCPは「描いて・見て・直す」を繰り返せる点で、最終成果物の品質に大きな差が生まれます。プレゼン資料や設計ドキュメントに掲載する図として十分な精度を目指す場合に、このメリットが顕著に発揮されます。

ステートレス生成とステートフル操作という2つのアプローチの判断基準

Excalidraw MCP連携には大きく分けて2つのアプローチが存在します。公式版MCPが採用する「ステートレス生成」は、プロンプトを入力すると完成図が一括で出力されるワンショット方式です。チャット画面内にインラインで表示されるため、手軽にダイアグラムを得たい場面に適しています。一方、コミュニティ版mcp_excalidrawが採用する「ステートフル操作」は、ライブキャンバス上に要素を逐次追加・編集していく方式で、AIが現在のキャンバス状態を認識しながら操作を積み重ねていきます。

判断基準は明確です。会議中のメモや簡易的な図解が目的であればステートレス生成の公式版が適しています。一方、複数回の修正を前提としたアーキテクチャ図の作成や、チームで共有・再編集するダイアグラムの構築にはステートフル操作のコミュニティ版が適しています。さらに、複数のAIエージェントが同一キャンバス上で同時に描画するマルチエージェント構成を想定する場合は、WebSocket同期機能を持つコミュニティ版が唯一の選択肢となります。プロジェクトの規模と図の用途に応じて、どちらのアプローチを採用するか事前に決定しておくことが、スムーズな導入への第一歩です。

公式版とコミュニティ版で異なるExcalidraw MCPサーバーの機能差と選定基準

2026年2月、Excalidraw公式チームがAnthropicと協力して公式MCPをリリースし、コミュニティ版と合わせて2系統のMCPサーバーが選択肢に加わりました。両者は設計思想が異なり、対象とするユースケースも明確に分かれます。ここでは機能差を具体的に比較し、どちらを選ぶべきかの判断基準を示します。

Excalidraw公式MCPが提供するワンショット生成の特徴と対応クライアント一覧

Excalidraw公式MCP（excalidraw/excalidraw-mcp）は、MCP Apps仕様に準拠したサーバーとして設計されています。最大の特徴は、プロンプトを送るとExcalidrawの手書き風ダイアグラムがチャットUIの中にストリーミング描画される点です。「draw an architecture diagram showing a user connecting to an API server which talks to a database」のような自然言語プロンプトを入力するだけで、カメラのビューポート制御を伴うスムーズなアニメーション付きで図が生成されます。生成後はインタラクティブなフルスクリーン編集モードに切り替えて手動での微調整も可能です。

対応クライアントはMCP Apps仕様をサポートするすべてのクライアントで、Claude Desktop、ChatGPT、VS Code、Gooseなどが含まれます。リモートMCPサーバーとしてhttps://excalidraw-mcp-app.vercel.app/mcpのURLを登録するだけで即時利用可能なため、ローカル環境構築が不要な点が大きなメリットです。Claude Desktopの場合はSettings → Connectors → Add custom connectorからURLを貼るだけの3ステップで導入が完了します。ローカル実行が必要な場合も、GitHubのReleasesからmcpbファイルをダウンロードしてダブルクリックするだけでインストールできます。

コミュニティ版mcp_excalidrawが持つ26ツールの全体構成とCRUD操作の実力

コミュニティ版mcp_excalidraw（yctimlin/mcp_excalidraw）は、v2.0で合計26のMCPツールを搭載しています。Element CRUD系としてcreate_element、get_element、update_element、delete_element、query_elements、batch_create_elements、duplicate_elementsの7ツールが用意されており、個別要素レベルでの完全な作成・読取・更新・削除操作が可能です。Layout系にはalign_elements、distribute_elements、group_elements、ungroup_elements、lock_elements、unlock_elementsの6ツールがあり、要素の整列・均等配置・グループ化を自動化できます。

公式版との最大の差別化ポイントは、AIが自分の描いた図を「見る」能力を持つ点です。describe_sceneは現在のキャンバス上の全要素を構造化テキストとして返し、get_canvas_screenshotはブラウザでレンダリングされた画像をそのまま取得します。この2つのツールにより、AIが「描いた結果を確認し、問題があれば修正する」という閉ループ改善を自律的に実行できます。単なる描画ツールではなく、AIにとっての「目と手」を兼ね備えたキャンバス操作環境といえます。

公式版とコミュニティ版を14項目で比較した機能対応表と選定フローチャート

両サーバーの機能差を正確に把握するため、主要14項目で比較した対応表を示します。どちらか一方が全面的に優れているわけではなく、ユースケースに応じた使い分けが求められます。

選定の判断軸はシンプルです。手軽にダイアグラムを生成したい場合は公式版、要素単位の精密な制御や反復改善が必要な場合はコミュニティ版を選択してください。両方を併用し、初期ラフを公式版で生成した後にコミュニティ版で精緻化するワークフローも有効です。

describe_sceneとget_canvas_screenshotによる閉ループ改善が生む品質差の実例

コミュニティ版のdescribe_sceneツールは、キャンバス上の全要素をJSON構造で返却します。各要素のtype、座標、サイズ、テキスト内容、接続関係などが含まれるため、AIは「現在のキャンバスにどの要素がどこに配置されているか」を正確に把握できます。さらにget_canvas_screenshotはブラウザで実際にレンダリングされた画像を取得するため、要素同士の重なりや余白のバランスといった視覚的な問題もAIが検出可能です。

実際の品質差は顕著に現れます。公式版のワンショット生成では、要素の配置が偏ったり接続線が交差したりした場合、図全体を再生成するしかありません。一方、コミュニティ版ではdescribe_sceneで現状を分析し、align_elementsで整列を掛け、update_elementで個別要素の位置を微調整し、再度get_canvas_screenshotで確認するというサイクルを回せます。あるユーザーの事例では、コードベースのPDFインポート機能を解析させ、現状仕様と改善案をExcalidraw上に自動図式化させた結果、AIが自律的に3回の修正サイクルを回し、人間による手直しなしで設計レビューに使える品質の図が得られたと報告されています。

Mermaid変換やスナップショット復元など公式版にない5機能の業務活用シーン

コミュニティ版が持ち、公式版にはない主要5機能の業務活用シーンを整理します。第一のcreate_from_mermaidは、既存のMermaid記法で書かれたフローチャートやシーケンス図をExcalidraw形式に変換します。すでにREADMEやドキュメントにMermaidで図を書いているチームが、プレゼン用に手書き風ビジュアルへ変換したい場面で活用できます。第二のsnapshot_sceneとrestore_snapshotは、キャンバスの状態を名前付きで保存・復元する機能です。設計案AとBを切り替えて比較検討する際に、スナップショットを切り替えるだけで瞬時に2案を見比べられます。

第三のexport_sceneとimport_sceneは、キャンバス全体を.excalidrawJSONファイルとして入出力する機能です。Gitリポジトリにコミットすることで図のバージョン管理が実現します。第四のexport_to_imageはPNGやSVG形式での画像エクスポートを行い、ドキュメント埋め込みに対応します。第五のexport_to_excalidraw_urlは、キャンバスの内容を暗号化してexcalidraw.comにアップロードし、誰でも開ける共有リンクを生成します。社外のクライアントやリモートメンバーとの共有に特に有効で、相手側にExcalidrawのインストールが不要な点が実用的です。

Claude DesktopへのExcalidraw MCP導入で失敗しないための環境構築と設定手順

Claude DesktopでExcalidraw MCPを使う方法は、公式版のリモート接続とコミュニティ版のローカル構築の2通りがあります。公式版はURL登録だけで完了しますが、コミュニティ版はリポジトリのCloneからサーバー起動まで複数のステップが必要です。ここでは両方の手順を、つまずきやすいポイントとあわせて解説します。

リポジトリCloneからnpm run buildまでの初回セットアップ4ステップ

コミュニティ版mcp_excalidrawのセットアップは4ステップで完了します。まずGitHubからリポジトリをクローンし、依存パッケージをインストールした後にビルドを実行し、最後にビルド成果物の存在を確認するという流れです。

1. ターミナルでgit clone https://github.com/yctimlin/mcp_excalidraw mcp_excalidrawを実行し、任意のディレクトリにリポジトリを取得します。プロジェクト単位でMCPを管理したい場合は、開発中のプロジェクトディレクトリ直下に配置するのが便利です。
2. cd mcp_excalidrawで移動した後、npm ciを実行して依存パッケージをlockfileに基づいて厳密にインストールします。npm installでも動作しますが、再現性の観点からnpm ciが推奨されます。
3. npm run buildを実行してTypeScriptをトランスパイルします。ビルドが完了するとdist/ディレクトリが生成されます。
4. ls -l dist/index.jsでファイルの存在とサイズを確認します。ファイルが表示されればセットアップ完了です。

この4ステップでつまずくケースの大半は、Node.jsのバージョン不足か、ネットワーク制限によるnpmパッケージのダウンロード失敗です。社内プロキシ環境の場合は、事前にnpm config set proxyを設定しておくことで回避できます。

claude_desktop_config.jsonへの記述内容とOS別ファイルパスの正確な指定方法

Claude DesktopのMCP設定は、JSON形式の設定ファイルに記述します。設定ファイルの配置場所はOSによって異なり、macOSでは~/Library/Application Support/Claude/claude_desktop_config.json、Windowsでは%APPDATA%\Claude\claude_desktop_config.json、Linuxでは~/.config/Claude/claude_desktop_config.jsonです。このファイルが存在しない場合は新規作成してください。

設定内容はmcpServersオブジェクト内にexcalidrawという名前でサーバー定義を記述します。commandにnodeを、argsにdist/index.jsの絶対パスを、envにEXPRESS_SERVER_URLとENABLE_CANVAS_SYNCを指定します。ここで最も多い設定ミスは、パスに/absolute/path/to/というGitHubのREADMEに記載されたプレースホルダーをそのまま記述してしまうケースです。実際の絶対パス（例：/Users/yourname/projects/mcp_excalidraw/dist/index.js）に置き換える必要があります。設定ファイルを保存したらClaude Desktopを再起動することで、MCPサーバーが認識されます。

CanvasサーバーとMCPサーバーを2ターミナルで同時起動する手順と確認コマンド

コミュニティ版を利用する際は、CanvasサーバーとMCPサーバーの2つを同時に起動しておく必要があります。Canvasサーバーはブラウザ向けのWeb UIとREST API・WebSocketを提供し、MCPサーバーはClaude Desktopとの通信を担当します。起動順序にも注意が必要で、Canvasサーバーを先に起動してからMCPサーバーを起動してください。MCPサーバーは起動時にEXPRESS_SERVER_URLで指定されたCanvasサーバーへの接続を試みるため、先にCanvasサーバーが稼働している必要があります。

具体的には、ターミナルを2つ開き、両方ともmcp_excalidraw/ディレクトリ内で操作します。ターミナル1でHOST=0.0.0.0 PORT=3000 npm run canvasを実行するとCanvasサーバーが起動し、ブラウザでhttp://localhost:3000にアクセスするとExcalidrawの画面が表示されます。ターミナル2でEXPRESS_SERVER_URL=http://localhost:3000 node dist/index.jsを実行するとMCPサーバーがstdioモードで起動します。Canvasサーバーの正常動作確認はcurl http://localhost:3000/healthで行えます。tmuxやiTerm2の画面分割を使って2ターミナルを同時表示しておくと、運用が効率的です。

Docker経由で導入する場合のhost.docker.internal設定とLinux固有の追加オプション

ローカルにNode.js環境を構築したくない場合は、Docker経由での導入が可能です。Canvasサーバーはdocker run -d -p 3000:3000 --name mcp-excalidraw-canvas ghcr.io/yctimlin/mcp_excalidraw-canvas:latestで起動できます。MCPサーバーの設定では、コンテナ内からホストマシン上のCanvasサーバーにアクセスするため、EXPRESS_SERVER_URLにhttp://host.docker.internal:3000を指定します。

host.docker.internalはDocker Desktop（macOS・Windows）で自動的に利用可能なホスト名ですが、Linux環境ではデフォルトでは名前解決されません。Linux上でDocker Composeを使用している場合はextra_hosts: ["host.docker.internal:host-gateway"]を追加し、docker runコマンドの場合は--add-host=host.docker.internal:host-gatewayオプションを付与する必要があります。代替手段として、Linuxのデフォルトブリッジネットワークのゲートウェイアドレスである172.17.0.1を直接指定する方法もあります。Docker環境特有のネットワーク設定は、Excalidraw MCPに限らずあらゆるMCPサーバーのDocker運用で共通する知識のため、一度理解しておくと応用が利きます。

公式版をリモートMCPとして3クリックで接続するConnectors設定の最短導入法

環境構築の手間を一切かけずにExcalidraw MCP連携を試したい場合は、公式版のリモートMCPサーバーが最適です。Vercel上にデプロイされたhttps://excalidraw-mcp-app.vercel.app/mcpというURLを登録するだけで、ローカル環境へのインストールなしに即座に利用を開始できます。Claude Desktopでの設定手順は3ステップです。Settings画面を開き、Connectorsタブに移動し、Add custom connectorで上記URLを貼り付けるだけです。

VS Codeからも同様にリモートMCPとして接続可能で、コマンドパレットからMCP: Add Server → HTTP → URLを入力する手順で設定できます。リモート接続のため、CanvasサーバーやMCPサーバーのローカル起動は不要ですが、生成された図はチャットUIのインライン表示となり、独立したブラウザウィンドウでのリアルタイム表示はありません。まずは公式版のリモート接続でExcalidraw MCP連携の体験を掴み、より高度な操作が必要になった段階でコミュニティ版のローカル構築に移行するという段階的アプローチが、学習コストを抑えた合理的な導入戦略です。

Claude CodeからExcalidraw MCPを操作するための登録方法と動作確認の実務フロー

Claude Codeは、ターミナル上で動作するエージェント型コーディングツールです。MCPサーバーの登録にはCLIコマンドを使用するため、Claude Desktopとは設定手順が異なります。このセクションでは、Claude Code固有の登録方法から動作確認、実際のプロンプト実行までの一連のフローを解説します。

claude mcp addコマンドでuser scopeとproject scopeを使い分ける判断基準

Claude CodeへのMCPサーバー登録はclaude mcp addコマンドで行います。scopeオプションには--scope userと--scope projectの2種類があり、用途に応じて使い分けます。--scope userはユーザーレベルの設定で、~/.claude配下に保存されるため、どのプロジェクトディレクトリからでもExcalidraw MCPを利用できます。個人の開発環境全体でExcalidrawを使いたい場合はこちらが適しています。

一方、--scope projectはプロジェクトルートに.mcp.jsonファイルを生成し、そのプロジェクト固有の設定として保存します。このファイルをGitリポジトリにコミットすれば、チームメンバー全員が同一のMCP設定を共有できるというメリットがあります。判断基準としては、個人利用ならuser scope、チーム共有ならproject scopeを選択してください。なお、同一名のMCPサーバーがuser scopeとproject scopeの両方に登録されている場合はproject scopeが優先されるため、プロジェクト固有のポート番号やパスで上書きしたいケースにも対応可能です。

EXPRESS_SERVER_URLのポート番号競合を避けるための設定値とデフォルト変更例

Excalidraw MCPのCanvasサーバーはデフォルトでポート3000を使用しますが、Reactの開発サーバーやNext.jsのデフォルトポートと競合するケースが頻発します。実際の開発プロジェクトではnpm run devがポート3000を占有していることが多いため、Canvasサーバーのポートを変更しておくのが安全です。Canvasサーバーの起動コマンドでPORT=3201のように任意のポートを指定し、MCP登録時のEXPRESS_SERVER_URLもそれに合わせてhttp://localhost:3201に変更します。

具体的な登録コマンドの例は次のとおりです。claude mcp add excalidraw --scope user -e EXPRESS_SERVER_URL=http://localhost:3201 -e ENABLE_CANVAS_SYNC=true -- node /Users/yourname/projects/mcp_excalidraw/dist/index.jsのように、-eオプションで環境変数を渡します。ポート番号は3000〜3999の範囲で自分の開発環境と衝突しない番号を選ぶのが慣例です。ポートが競合している場合、MCPサーバー起動時にECONNREFUSEDエラーやAddress already in useエラーが発生するため、lsof -i :3000で使用状況を事前に確認しておくと確実です。

MCP登録後にcurl healthcheckとMCP Inspectorで接続を検証する2段階テスト

MCP登録が完了した後の動作確認は2段階で行います。第1段階はCanvasサーバー単体のヘルスチェックです。ターミナルでcurl http://localhost:3201/healthを実行し、正常なレスポンスが返ることを確認します。このテストが失敗する場合は、Canvasサーバーが起動していないか、ポート番号が間違っているかのどちらかです。

第2段階はMCPサーバーとの通信テストです。MCP Inspectorを使ってnpx @modelcontextprotocol/inspector --cli -e EXPRESS_SERVER_URL=http://localhost:3201 -e ENABLE_CANVAS_SYNC=true -- node dist/index.js --method tools/listを実行すると、利用可能な全26ツールの一覧が返却されます。さらに、--method tools/call --tool-name create_element --tool-arg type=rectangle --tool-arg x=100 --tool-arg y=100 --tool-arg width=300 --tool-arg height=200を追加すれば、実際に矩形要素を作成するテストも可能です。ブラウザでhttp://localhost:3201を開いておけば、矩形がリアルタイムに描画される様子を確認できます。この2段階テストに合格すれば、Claude Codeからの操作も問題なく動作します。

自然言語プロンプトでアーキテクチャ図を生成する実践的な指示文テンプレート

Excalidraw MCPの動作確認が取れたら、実際にClaude Codeから自然言語プロンプトで図を生成してみましょう。効果的な指示文には、対象範囲・図の種類・含めるべき要素の3要素を明示することが重要です。曖昧な指示では、AIが過剰に要素を詰め込んだり、必要な情報が欠落したりする傾向があります。

実践的な指示文テンプレートとしては「このCode Baseの〇〇機能を解析し、現状の処理フローと改善案をmcp_excalidrawを使って図式化してください」という形式が有効です。コードベースのコンテキストを先にAIに与えた上で、ExcalidrawのMCPツールを使った描画を依頼するという2段構えの指示が、精度の高い図を得るコツです。また「要素間は矢印で接続し、各ボックスには処理名とデータフローの方向を記載してください」のような具体的な視覚要件を加えると、AIがレイアウトツールまで活用して整った図を生成する確率が上がります。生成後はdescribe_sceneで構造を確認し、不足があれば追加指示を出すという反復フローを前提にしたプロンプト設計が推奨されます。

登録済みMCPの一覧確認・削除・再設定をターミナルから行うトラブル復旧手順

設定ミスや環境変更でMCPサーバーの再登録が必要になった場合、Claude CodeのCLIコマンドで対応します。claude mcp listを実行すると、現在登録されているすべてのMCPサーバーが一覧表示され、名前・scope・コマンド・環境変数を確認できます。設定に誤りがある場合は、claude mcp remove excalidrawで該当サーバーを削除した後、正しいパラメータで再登録する流れです。

よくあるトラブル復旧パターンとして、絶対パスの変更（プロジェクトディレクトリの移動後）、ポート番号の変更、Docker化への切り替えの3つがあります。いずれの場合も「remove → add」の2コマンドで対処可能です。なお、--scope userで登録した設定は~/.claude配下のファイルに、--scope projectで登録した設定はプロジェクトルートの.mcp.jsonに保存されているため、直接ファイルを編集することも可能です。ただし、手動編集はJSON構文エラーのリスクがあるため、CLIコマンド経由での操作を推奨します。

CursorやCodex CLIなど主要AIエディタごとのExcalidraw MCP設定差分と注意点

Excalidraw MCPサーバーはstdio経由で通信するため、MCP対応のあらゆるクライアントから利用できます。ただし、設定ファイルの形式や配置場所はクライアントごとに異なります。このセクションでは、主要5クライアントの設定方法を具体的に比較し、共通する落とし穴を解説します。

Cursorの.cursor/mcp.jsonに記述するローカル版とDocker版の設定テンプレート

CursorでExcalidraw MCPを利用する場合、プロジェクトルートに.cursor/mcp.jsonを作成するか、グローバル設定として~/.cursor/mcp.jsonに記述します。JSON構造はClaude Desktopと同一で、mcpServersオブジェクト内にサーバー定義を記述する形式です。ローカル版の設定ではcommandにnode、argsにdist/index.jsの絶対パス、envにEXPRESS_SERVER_URLとENABLE_CANVAS_SYNCを指定します。

Docker版の設定ではcommandにdockerを、argsにrun・-i・–rm・-eオプションとイメージ名ghcr.io/yctimlin/mcp_excalidraw:latestを配列で指定します。Cursorではプロジェクトレベルの設定ファイル（.cursor/mcp.json）がGitリポジトリに含まれる場合、チームメンバーに自動共有される仕組みがあります。ただし、絶対パスが個人の環境に依存するため、チーム共有時はDocker版の設定を用いるか、パスを環境変数化する工夫が必要です。Cursorの設定変更後はエディタの再起動が必要な点にも注意してください。

Codex CLIのcodex mcp addコマンドで環境変数を渡す際の書式とエスケープ注意点

OpenAIのCodex CLIでもExcalidraw MCPは利用可能です。登録コマンドはcodex mcp add excalidraw --env EXPRESS_SERVER_URL=http://localhost:3000 --env ENABLE_CANVAS_SYNC=true -- node /absolute/path/to/mcp_excalidraw/dist/index.jsです。Claude Codeの-eオプションとは異なり、Codex CLIでは--envという長形式オプションを使用する点に注意してください。

環境変数の値にスペースや特殊文字が含まれる場合は、シェルのエスケープ規則に従ってクォートで囲む必要があります。たとえば、パスにスペースが含まれる場合は-- node "/Users/your name/projects/mcp_excalidraw/dist/index.js"のようにダブルクォートで囲みます。管理コマンドはClaude Codeと同様にcodex mcp listで一覧確認、codex mcp remove excalidrawで削除が可能です。CodexとClaude Codeの両方を併用しているチームでは、同じCanvasサーバーに対して複数のMCPクライアントから同時にアクセスできるため、各メンバーが使い慣れたエディタを選択しつつ同一キャンバスで協働する構成も実現可能です。

OpenCodeのopencode.jsonで設定するtype: local指定とenvironment記述の実例

OpenCodeは~/.config/opencode/opencode.jsonまたはプロジェクトルートのopencode.jsonに設定を記述します。他のクライアントと異なるのは、JSON構造にスキーマURLの指定とtypeフィールドが存在する点です。mcpオブジェクト内にexcalidrawキーを作成し、typeにlocalを、commandに["node", "/absolute/path/to/mcp_excalidraw/dist/index.js"]を配列形式で、enabledにtrueを、environmentにオブジェクト形式で環境変数を指定します。

Claude DesktopやCursorの設定と比べると、commandがargsと分離されていない配列形式である点、envではなくenvironmentというキー名である点が差分です。Docker版の場合はcommand配列にdocker runの全引数を順番に列挙する必要があり、設定が長くなりがちです。OpenCodeの設定ファイルは$schemaフィールドにhttps://opencode.ai/config.jsonを指定することでIDEの自動補完が効くため、記述ミスの予防に活用してください。設定の有効化にはOpenCodeの再起動が必要です。

Google Antigravityのmcp_config.jsonにおけるパス指定とClaude Desktop設定との差分

GoogleのAntigravityは~/.gemini/antigravity/mcp_config.jsonに設定ファイルを配置します。JSON構造はClaude Desktopの設定ファイルとほぼ同一で、mcpServersオブジェクト内にサーバー定義を記述する形式です。commandにnode、argsに絶対パス、envに環境変数を指定するという点は完全に共通しています。

Claude Desktopとの実質的な差分は、設定ファイルの配置パスのみです。macOSの場合、Claude Desktopは~/Library/Application Support/Claude/配下ですが、Antigravityは~/.gemini/antigravity/配下となります。両クライアントを併用する場合は、同一のMCPサーバー定義を両方の設定ファイルにコピーするだけで済みます。Docker版の設定もClaude Desktopと同じ形式で記述可能です。Antigravity固有の注意点として、Geminiモデルとのやり取りにおけるツール呼び出しの書式がClaude系と若干異なる場合がありますが、MCPのstdioプロトコルレベルではクライアント非依存のため、サーバー側の設定変更は不要です。

5クライアント横断で共通する設定ミス3パターンと即座に切り分ける確認手順

Claude Desktop、Claude Code、Cursor、Codex CLI、OpenCodeの5クライアントに共通する設定ミスは大きく3パターンに集約されます。第一に、dist/index.jsへの絶対パスの誤りです。相対パスで記述すると、クライアントの作業ディレクトリ次第で読み込みに失敗します。切り分けとしてnode /記述したパス/dist/index.jsをターミナルで直接実行し、エラーが出るかどうかで判別できます。

第二に、Canvasサーバーの未起動です。MCPサーバーは起動時にCanvasサーバーへの接続を試みるため、Canvasサーバーが停止しているとconnection refusedエラーが発生します。curl http://localhost:3000/health（ポートは環境に合わせて変更）で即座に確認できます。第三に、環境変数の指定漏れです。EXPRESS_SERVER_URLが未設定の場合、MCPサーバーはデフォルトのhttp://localhost:3000に接続しようとしますが、ポート番号を変更している場合は接続に失敗します。これらの3パターンを順番にチェックするだけで、5クライアントのいずれにおいても設定問題の9割以上を切り分けられます。

Excalidraw MCP全26ツールの実務用途別分類と図解品質を高める活用パターン

コミュニティ版mcp_excalidrawが搭載する26のMCPツールは、Element CRUD・Layout・Scene Awareness・File I/O・State Management・Viewport・Design Guideの7カテゴリに分類されます。すべてのツールを一度に使いこなす必要はなく、実務上の用途に応じて段階的に活用範囲を広げていくのが効果的です。

Element CRUD系7ツールで要素単位の作成・更新・削除を行う基本操作と注意点

Element CRUD系は最も基本的かつ使用頻度の高いツール群です。create_elementはtype（rectangle、ellipse、diamond、text、line、arrowなど）、座標、サイズ、テキスト内容を指定して要素を1つ作成します。batch_create_elementsは複数要素を1回のリクエストで一括作成でき、アーキテクチャ図のように多数の要素を配置する場面で効率的です。get_elementはIDを指定して要素の現在のプロパティを取得し、query_elementsは条件に合致する要素を検索します。

update_elementは既存要素の座標・サイズ・テキスト・色などのプロパティを更新し、delete_elementは要素を削除します。duplicate_elementsは既存要素の複製を行い、類似した構成要素を繰り返し配置する場面で便利です。注意点として、v1.x系ではbatch_create_elementsで作成した要素のIDが正しく保持されないバグがあり、作成直後にupdate_elementやdelete_elementが失敗するケースがありました。v2.0ではこのバグが修正されていますが、古いバージョンを使用している場合はアップデートが必要です。

align_elementsとdistribute_elementsによるレイアウト自動整列の効果と適用条件

AIが要素を生成した直後の配置は、座標指定の精度に依存するため、要素同士の整列が微妙にずれることがあります。align_elementsは指定した複数要素を左揃え・中央揃え・右揃え・上揃え・垂直中央揃え・下揃えのいずれかに整列させるツールで、見た目の統一感を一括で実現できます。distribute_elementsは要素間の間隔を均等に調整するツールで、水平方向または垂直方向の均等配置が可能です。

これらのレイアウトツールの適用条件は、3つ以上の要素が同一方向に並んでいる場合です。2要素のみの整列では効果が限定的で、update_elementで直接座標を指定した方が効率的なケースもあります。実務上の活用パターンとしては、AIがbatch_create_elementsで複数ボックスを配置した後、align_elementsで水平方向に中央揃えし、distribute_elementsで垂直方向に等間隔配置するという2段階の整列処理が定番です。v2.0でalign_elementsとdistribute_elementsの実装が完全に刷新され、v1.x系で発生していた整列位置のずれが解消されています。

export_sceneとimport_sceneを使ったJSON形式でのダイアグラム永続化フロー

コミュニティ版mcp_excalidrawのCanvasサーバーはインメモリストレージを採用しているため、サーバーを再起動するとキャンバス上のすべての要素が消失します。この問題を解決するのがexport_sceneとimport_sceneのFile I/Oツールです。export_sceneはキャンバスの全要素を.excalidrawJSON形式でエクスポートし、import_sceneは保存済みのJSONファイルからキャンバスに要素を復元します。

永続化フローの基本は「作業のキリが良い段階でexport_scene → JSONファイルをプロジェクトディレクトリに保存 → 必要に応じてGitコミット」です。Agent Skillに含まれるヘルパースクリプトexport-elements.cjsを使えば、コマンドラインからnode skills/excalidraw-skill/scripts/export-elements.cjs --out diagram.elements.jsonを実行するだけでエクスポートが完了します。インポート時はimport-elements.cjsに--mode batch（追加モード）または--mode sync（キャンバスを完全に置き換えるモード）を指定できます。チーム開発では、設計図のJSONファイルをGitで管理し、Pull Requestで図の変更差分をレビューするワークフローも実現可能です。

read_diagram_guideが返すカラーパレットとサイズルールで図解品質が上がる理由

AIが生成するダイアグラムの品質を大きく左右するのが、色やサイズの一貫性です。read_diagram_guideはExcalidrawでの作図におけるベストプラクティスをまとめたデザインガイドを返却するツールで、推奨カラーパレット、要素サイズの基準値、レイアウトパターン、避けるべきアンチパターンが含まれています。AIエージェントがこのガイドを参照してから作図を行うことで、色の統一感やサイズのバランスが格段に向上します。

具体的には、デザインガイドには「主要ボックスは幅200〜300・高さ80〜120を基準とする」「接続線は要素間に最低40pxの余白を確保する」「背景色はExcalidrawの標準パレットから選択する」といったルールが記載されています。AIがこれらのルールを参照せずに作図すると、テキストがボックスからはみ出したり、要素が密集しすぎて視認性が低下したりする傾向があります。実務上は、最初のプロンプトで「read_diagram_guideを参照してからアーキテクチャ図を作成してください」と明示的に指示するか、Agent Skillの自動ワークフローに組み込むことで、毎回安定した品質のダイアグラムを得られるようになります。

set_viewportによるズームフィットとscrollToContentで完成図を即確認する操作例

set_viewportはキャンバスの表示範囲を制御するツールで、3つのモードを持っています。scrollToContentモードはキャンバス上の全要素が画面内に収まるようにズームレベルと表示位置を自動調整します。scrollToElementIdモードは特定の要素IDを指定してその要素が画面中央に来るようにスクロールします。手動モードではzoom値とx・yオフセットを直接指定できます。

実務上の活用パターンとして最も頻度が高いのは、AIがダイアグラムの作成を完了した直後にset_viewportのscrollToContentモードを呼び出し、完成図全体を画面内に収めるケースです。AIが大きなアーキテクチャ図を生成した場合、ブラウザで表示しているCanvasのビューポートが一部の要素しか映していないことがあります。scrollToContentを実行すれば自動的にズームアウトして全体像が表示されるため、人間が手動でスクロールやズーム調整する手間を省けます。Agent Skillのワークフローでは、作図の最終ステップとしてset_viewportを組み込むことが推奨されています。

draw.io MCPやMermaid生成と比較したExcalidraw MCP連携の強みと使い分け判断基準

2026年2月にはdraw.io公式MCPもリリースされ、AIを活用したダイアグラム生成ツールの選択肢が一気に広がりました。Mermaid記法も含めた3つの選択肢を比較し、プロジェクトの特性に応じた最適な使い分け基準を整理します。

draw.io公式MCPが対応するXML・CSV・Mermaid 3形式とExcalidrawとの出力品質比較

draw.io公式MCP（@drawio/mcp）は、npmパッケージとしてnpx @drawio/mcpの1コマンドで導入できるのが特徴です。入力形式としてdraw.io XML、CSV（draw.io独自のCSVインポート形式）、Mermaid.jsの3種類に対応しており、AIが生成したテキストデータをdraw.ioエディタで直接開く仕組みです。既存のMermaid図をdraw.io形式に変換する機能も備えているため、Mermaidで書き溜めた資産をdraw.ioの豊富なテンプレートに移行したいケースに適しています。

出力品質の面では、draw.ioは精密な製図向けの整然としたレイアウトが得意で、Excalidrawは手書き風の柔らかいビジュアルが特徴です。draw.ioのMCPは生成した図をdraw.ioデスクトップアプリやWebエディタで開くため、後からの手動編集の自由度が高く、AWS構成図のような公式アイコンを用いた詳細な図に向いています。一方、Excalidraw MCPはプレゼンや設計レビューの初期検討段階で「まだ確定ではない」という印象を与えるドラフト感のある図が自然に生成されます。

Mermaid単体生成のトークン効率とExcalidraw MCP経由変換の表現自由度トレードオフ

Mermaid記法は、AIが図を生成する際のトークン効率が最も高い選択肢です。フローチャートやシーケンス図をテキスト数十行で記述でき、GitHubのMarkdownプレビューでそのまま表示される利便性があります。しかし、配置位置やサイズの細かい制御はMermaidの自動レイアウトに依存するため、複雑な図では意図しない要素の配置や線の交差が発生しやすく、手動での調整手段も限られます。

Excalidraw MCP経由での図解生成はMermaidに比べてトークン消費量が多くなりますが、座標レベルの配置制御が可能で、表現の自由度は圧倒的に高くなります。さらに、コミュニティ版のcreate_from_mermaidツールを使えば、既存のMermaid記法をExcalidraw形式に変換した上で手書き風にレンダリングし、そこからupdate_elementで微調整を加えるという「Mermaidの効率性 × Excalidrawの表現力」を両立するワークフローが可能です。READMEのMermaid図をプレゼン向けにビジュアルアップグレードする場面で特に効果を発揮します。

リアルタイム同期と手書き風UIという視覚的差別化が刺さるプレゼン・設計レビュー場面

Excalidraw MCP連携が他のダイアグラムツールに対して最も差別化されるのは、リアルタイム同期と手書き風UIの組み合わせが生むライブデモ効果です。設計レビューの場で「この部分のフローを変えたい」という要望が出た際に、Claudeに追加指示を出すとブラウザ上のExcalidrawキャンバスがリアルタイムに更新されていく様子を参加者全員で確認できます。draw.ioやMermaidでは「AIが図を再生成する → 結果を表示する」という非同期のステップが入るため、この即時性は実現できません。

手書き風UIのビジュアル特性も重要な差別化要素です。設計レビューの初期段階では「これは確定した仕様図ではなく、議論のためのたたき台です」というメッセージを図の見た目で暗に伝えることが、建設的なフィードバックを引き出すコツとして知られています。Excalidrawの手書き風レンダリングはこの目的に最適で、参加者が「きれいすぎる図」に対して感じる「今さら変更を提案しにくい」という心理的障壁を取り除きます。クライアント向けの最終納品物にはdraw.ioの整然としたレイアウト、チーム内の設計検討にはExcalidrawの手書き風、という使い分けが効果的です。

チーム共有性・バージョン管理・編集後の再利用性を3軸で評価した選定マトリクス

3つのツールをチーム共有性・バージョン管理・編集後の再利用性の3軸で評価すると、それぞれに明確な強みと弱みが見えてきます。

この評価から導かれる選定基準は明確です。ドキュメントへの埋め込みと差分レビューを最優先するならMermaid、高品質な製図と豊富なテンプレートが必要ならdraw.io MCP、AIとの反復的な共同作業とリアルタイム編集を重視するならExcalidraw MCPが最適解です。プロジェクトの中で複数の場面が存在する場合は、場面ごとにツールを使い分けることが現実的な運用方針となります。

フローチャートはdraw.io、アーキテクチャ概要図はExcalidrawという使い分け実例

実際の開発プロジェクトにおける使い分け事例として、処理フローの可視化にはdraw.io MCP、システム全体のアーキテクチャ概要図にはExcalidraw MCPを採用するパターンが効果的です。フローチャートは条件分岐やループの正確な表現が求められるため、draw.ioの整然としたレイアウトと豊富なシェイプライブラリが適しています。一方、アーキテクチャ概要図はシステム全体の構造を俯瞰する目的で使われるため、厳密さよりも直感的な理解しやすさが求められ、Excalidrawの手書き風ビジュアルが効果を発揮します。

この使い分けをMCPの観点で実現するには、Claude CodeやCursor内で両方のMCPサーバーを登録しておき、プロンプトで使用するツールを明示的に指示します。「draw.io MCPを使ってログイン処理のフローチャートを作成してください」「Excalidraw MCPを使ってマイクロサービスの全体構成図を描いてください」のように使い分ければ、1つのAIクライアントから両ツールの長所を活かしたダイアグラムを得られます。AIエージェントが用途に応じて最適なツールを自動選択する仕組みをAgent Skillとして定義しておくと、さらに運用が洗練されます。

Excalidraw MCP連携で頻出するエラー5パターンと現場で即使えるトラブル対処法

Excalidraw MCP連携は複数のプロセスとネットワーク通信が関わるため、初回導入時やDocker環境への移行時にエラーが発生しやすい領域です。ここでは実際に報告されている頻出エラーの発生条件と対処法を5パターンに整理します。

EXPRESS_SERVER_URL未設定で発生するconnection refusedの原因と1行修正の対処法

最も多く報告されているエラーが、MCPサーバー起動時に発生するECONNREFUSED（connection refused）です。このエラーの原因は大きく2つに分かれます。第一に、Canvasサーバーが起動していない状態でMCPサーバーを起動した場合です。MCPサーバーはEXPRESS_SERVER_URLで指定されたアドレスに対してHTTPリクエストを送信するため、接続先が応答しなければ即座にエラーとなります。

第二に、EXPRESS_SERVER_URL環境変数が未設定または誤ったポート番号が指定されている場合です。未設定の場合はデフォルト値のhttp://localhost:3000が使用されますが、Canvasサーバーを別のポートで起動していればポート不一致でエラーが出ます。対処法は単純で、まずcurl http://localhost:3000/health（ポートは実際の設定に合わせる）でCanvasサーバーの稼働を確認し、応答がなければCanvasサーバーを起動します。ポート番号が異なる場合は、EXPRESS_SERVER_URL=http://localhost:正しいポートをMCPサーバーの起動コマンドまたは設定ファイルに追記するだけで解決します。

npm run build失敗時にNode.jsバージョン不一致を疑うべき判断基準と確認コマンド

npm run buildでTypeScriptのトランスパイルが失敗する場合、最初に確認すべきはNode.jsのバージョンです。mcp_excalidrawはNode.js 18以上を要件としており、それ以前のバージョンではESモジュール構文やTypeScriptの一部機能がサポートされないため、ビルドエラーが発生します。node -vを実行して表示されるバージョンが18未満であれば、Node.jsのアップデートが必要です。

Node.jsバージョン以外のビルド失敗パターンとしては、npm ci段階でのパッケージ解決エラーがあります。社内プロキシ環境でnpmレジストリにアクセスできない場合、npm config set proxy http://proxy.example.com:8080とnpm config set https-proxy http://proxy.example.com:8080を設定する必要があります。また、package-lock.jsonとNode.jsバージョンの組み合わせによっては依存関係の解決に失敗することがあり、その場合はrm -rf node_modules package-lock.jsonで依存関係を初期化した後、npm installで再インストールすると解消することが多いです。ビルド成功の判定はls -l dist/index.jsでファイルが存在し、サイズが0でなければ問題ありません。

Docker環境でhost.docker.internalが解決されないLinux特有の問題と–add-host対処

Docker Desktop（macOS・Windows）ではhost.docker.internalという特殊なDNS名がコンテナ内から自動的に利用可能で、ホストマシンのlocalhostにアクセスできます。しかし、Linux環境のDockerではhost.docker.internalがデフォルトでは名前解決されず、Could not resolve host: host.docker.internalやgetaddrinfo ENOTFOUND host.docker.internalといったエラーが発生します。

対処法はdocker runコマンドに--add-host=host.docker.internal:host-gatewayオプションを追加することです。これにより、コンテナ内のhostsファイルにhost.docker.internalの名前解決エントリが追加され、ホストマシンへのアクセスが可能になります。Docker Composeを使用している場合は、サービス定義にextra_hosts: ["host.docker.internal:host-gateway"]を追加します。代替手段として、EXPRESS_SERVER_URLにDockerのデフォルトブリッジネットワークのゲートウェイアドレスhttp://172.17.0.1:3000を直接指定する方法もありますが、ネットワーク構成によってはアドレスが異なるためdocker network inspect bridgeで実際のゲートウェイアドレスを確認してから設定するのが安全です。

バッチ作成後にupdate_elementが失敗するID保持バグの発生条件とv2.0での修正内容

v1.x系のmcp_excalidrawには、batch_create_elementsで複数要素を一括作成した直後にupdate_elementやdelete_elementが失敗するという既知のバグが存在していました。原因は、バッチ作成時にサーバー側で要素IDが正しく保持されず、AIが取得したIDと実際にキャンバス上に存在する要素のIDが不一致になるという問題です。この場合、update_elementに渡したIDに対応する要素が見つからないため「element not found」エラーが返されます。

発生条件は「batch_create_elementsで3つ以上の要素を同時作成し、その直後に個別要素のID指定操作を行う」というパターンです。v2.0ではPR #34でこのバグが修正され、バッチ作成時にも各要素のIDが正しく保持されるようになりました。v1.x系を使用していて本エラーが発生する場合は、git pull origin mainで最新版を取得し、npm ci && npm run buildで再ビルドすることで解消します。修正済みバージョンを使っているかどうかは、git log --oneline | head -20でコミット履歴を確認し、ID保持関連の修正コミットが含まれていることで判定できます。

インメモリ保存によるサーバー再起動時のデータ消失を防ぐexport_scene運用ルール

コミュニティ版mcp_excalidrawのCanvasサーバーは、すべての要素データをメモリ上に保持しています。このため、サーバープロセスの再起動やマシンの再起動を行うと、キャンバス上のすべてのダイアグラムが消失します。これはバグではなく設計上の仕様であり、永続的なストレージ機能は今後のTODO項目として公式に記載されています。

データ消失を防ぐための運用ルールは3段階で設定するのが効果的です。第一に、意味のある作業区切りごとにexport_sceneでJSONファイルにエクスポートする習慣をつけます。ファイル名には日付やバージョン番号を含め（例：architecture-v2-20260214.excalidraw）、どの時点の図かを判別できるようにします。第二に、エクスポートしたJSONファイルをプロジェクトのGitリポジトリにコミットし、バージョン管理の対象に含めます。第三に、サーバー再起動後はimport_sceneで最新のJSONファイルを読み込んでキャンバスを復元します。snapshot_sceneとrestore_snapshotはサーバーのメモリ内で動作するため、サーバー再起動では保持されない点に注意してください。スナップショットは「同一セッション内での設計案A/B比較」に使い、セッションをまたぐ永続化には必ずexport_sceneを使用するという棲み分けが重要です。

開発チームがExcalidraw MCP連携を定着させるための運用設計とスキル活用戦略

個人の開発環境でExcalidraw MCP連携が動作することと、チーム全体で定着した運用フローとして機能することには大きな隔たりがあります。このセクションでは、Agent Skillの活用、設定の標準化、チーム開発ワークフローへの組み込み方を具体的に解説します。

Agent Skillフォルダ構成のSKILL.mdとcheatsheet.mdが果たす役割と導入3ステップ

mcp_excalidrawリポジトリにはskills/excalidraw-skill/というAgent Skillフォルダが同梱されています。このフォルダはSKILL.md（ワークフロープレイブック）、references/cheatsheet.md（MCPツールとREST APIのリファレンス）、scripts/（ヘルパースクリプト群）の3要素で構成されています。SKILL.mdはAIエージェントが参照するステップバイステップのガイドで、「最初にread_diagram_guideでデザインルールを読み込む → 要素を作成する → describe_sceneで確認する → set_viewportで全体表示する」という作図ワークフローが定義されています。

導入は3ステップで完了します。第一に、Claude Codeの場合はmkdir -p ~/.claude/skillsでスキルディレクトリを作成します。第二に、cp -R skills/excalidraw-skill ~/.claude/skills/excalidraw-skillでスキルファイルをコピーします。第三に、Claude Code内で/excalidraw-skillと入力してスキルを呼び出し、動作を確認します。プロジェクトレベルで導入する場合は、コピー先を/path/to/your/project/.claude/skills/に変更し、Gitリポジトリにコミットすればチームメンバー全員が同じスキルを利用できます。Codex CLIの場合は~/.codex/skills/にコピーする点だけが異なります。

export-elements.cjsによるJSON書き出しとGitコミットで図をコード管理する方法

Agent Skillに含まれるヘルパースクリプトexport-elements.cjsは、Canvasサーバーから全要素をJSON形式でエクスポートするNode.jsスクリプトです。実行方法はEXPRESS_SERVER_URL=http://localhost:3201 node skills/excalidraw-skill/scripts/export-elements.cjs --out diagram.elements.jsonで、--outオプションで出力ファイルパスを指定します。エクスポートされたJSONファイルには、各要素のtype、座標、サイズ、テキスト内容、スタイル情報がすべて含まれています。

このJSONファイルをGitリポジトリのdocs/diagrams/ディレクトリなどに配置し、コードと同様にバージョン管理するのが推奨パターンです。Pull Requestの差分で図の変更内容をレビューする際に、JSON形式であれば「どの要素が追加され、どの要素の座標が変更されたか」がdiffとして可視化されます。対になるスクリプトimport-elements.cjsは--mode syncオプションでキャンバスをファイルの内容に完全一致させるモードを備えているため、「mainブランチのJSONファイルからキャンバスを復元する」というCI/CDパイプラインへの組み込みも技術的に可能です。

scope projectで.mcp.jsonを共有しチーム全員が同一MCP設定を使う標準化手順

チーム開発でExcalidraw MCP連携を標準化するには、--scope projectで生成される.mcp.jsonファイルをGitリポジトリに含めるのが最も確実な方法です。claude mcp add excalidraw --scope project -e EXPRESS_SERVER_URL=http://localhost:3201 -e ENABLE_CANVAS_SYNC=true -- node ./mcp_excalidraw/dist/index.jsを実行すると、プロジェクトルートに.mcp.jsonが生成されます。

ただし、dist/index.jsのパスが相対パスか絶対パスかによってチーム内での互換性が変わります。絶対パスを使用するとメンバーごとのディレクトリ構成の違いでエラーが発生するため、mcp_excalidrawをプロジェクトディレクトリ内にサブディレクトリとして配置し、./mcp_excalidraw/dist/index.jsのような相対パスで記述するのがベストプラクティスです。READMEに「初回セットアップ時にcd mcp_excalidraw && npm ci && npm run buildを実行すること」と明記しておけば、新しいメンバーが参加した際のオンボーディングもスムーズになります。Docker版を使う場合は環境依存がさらに減るため、チーム標準化のハードルが下がります。

コードベース解析→図解生成→レビューという3フェーズ開発ワークフローの設計例

Excalidraw MCP連携をチームの開発ワークフローに組み込む際の設計例として、「コードベース解析 → 図解生成 → レビュー」の3フェーズモデルが効果的です。フェーズ1では、Claude Codeに対象モジュールのコードベースを読み込ませ、処理フローやデータフロー、依存関係を分析させます。フェーズ2では、分析結果をもとにExcalidraw MCPのツール群を使ってアーキテクチャ図やシーケンス図を自動生成します。フェーズ3では、生成された図をチームメンバーとレビューし、修正が必要な箇所をAIに追加指示して改善します。

この3フェーズを1つのプロンプトで実行する実践的なテンプレートとしては「このCode Baseの〇〇機能を解析し、現状の処理フローと改善案をmcp_excalidrawを使って図式化してください。作成後はdescribe_sceneで配置を確認し、必要に応じてalign_elementsで整列してください」という形式が有効です。AIが自律的にフェーズ1〜2を実行し、フェーズ3の入口（整列済みの図の提示）まで完了させるため、人間はレビューと意思決定に集中できます。レビュー結果をもとに「〇〇コンポーネントを追加して」「矢印の方向を逆にして」と追加指示を出すだけで図が更新されるため、従来の「設計書を手動で修正する」作業と比較して大幅な時間短縮が期待できます。

複数エージェントが同一Canvasに同時描画するマルチエージェント構成の実務的な制約と対策

コミュニティ版mcp_excalidrawは、複数のAIエージェントが同一のCanvasサーバーに同時接続して描画できるマルチエージェント対応を備えています。WebSocket経由でリアルタイム同期が行われるため、エージェントAがフロントエンドのコンポーネント図を描きながら、エージェントBがバックエンドのAPI構成図を同時に描画するといった並列作業が技術的に可能です。公式版MCPがシングルユーザー前提の設計であるのに対し、この並列処理能力はコミュニティ版の大きな特徴です。

ただし、実務上の制約がいくつか存在します。第一に、複数エージェントが同じ領域に要素を配置しようとした場合、要素の重なりが発生するリスクがあります。対策として、キャンバスをエリア分割し、各エージェントの描画範囲を座標レベルで指定する（例：エージェントAはx:0〜500、エージェントBはx:600〜1100）というルールを設けます。第二に、インメモリストレージの同時書き込みによるデータ不整合のリスクがあります。現時点では排他制御の仕組みがないため、同一要素に対する同時更新は避ける必要があります。第三に、サーバーのメモリ消費量が要素数に比例して増加するため、大量の要素を持つ複雑な図ではパフォーマンス低下の可能性があります。これらの制約を理解した上で、エリア分割と作業順序の調整を行えば、マルチエージェント構成によるダイアグラム作成の生産性向上が実現できます。