--- title: "Excalidraw MCPの導入と使い方｜Claude Code・Cursor・Codex設定と3実装の選び方【v2.1対応】" url: "https://www.issoh.co.jp/tech/details/10968/" published: 2026-02-13 updated: 2026-10-17 categories: ["AIエージェント・MCP"] publisher: "株式会社一創" --- # Excalidraw MCPの導入と使い方｜Claude Code・Cursor・Codex設定と3実装の選び方【v2.1対応】 Excalidraw MCPは、Model Context Protocol（MCP）を通じてAIエージェントにExcalidrawのキャンバスを操作させる仕組みです。ただし「Excalidraw MCP」と呼ばれる実装は複数あり、代表的な3系統だけを見ても、チャット内に図を1枚流し込む公式版、コーディングエージェントが描いて・見て・直せるコミュニティ版 `mcp-excalidraw-server`、有料のExcalidraw+ワークスペースにつなぐExcalidraw+ MCPでは、できることがまるで違います。この記事では3つの選び方、Claude Code・Claude Desktop・Cursor・Codex CLIでの設定、そして2026年10月4日公開のコミュニティ版 v2.1.2 を実際に動かして確かめた挙動（ブラウザ不要になったスクリーンショット、日本語ラベルの扱い、終了コード）をまとめます。Excalidraw本体をブラウザで使う手順やDockerでのセルフホストは[Excalidrawの使い方とDockerセルフホスト手順](/tech/details/17487/)で扱っています。 ## まとめ - **Claude Code・Codex CLI・Cursorで図を作らせるならコミュニティ版**。最新は 2.1.2（npm 2026-10-04）。導入は `claude mcp add excalidraw --scope user -- npx -y mcp-excalidraw-server` の1行で、cloneもビルドも要らない。 - **v2.0でNode.js 20以上が必須になった**（v1.xは18以上）。Node 18のままだと起動しない。 - **v2.1でスクリーンショットと画像書き出しにブラウザのタブが要らなくなった**。タブが必要なのはMermaid変換と `set_viewport` だけ。`.excalidraw` ファイルからPNGを作る `render` はキャンバスサーバーすら不要。 - **日本語ラベルは同梱フォントに含まれない**。ヘッドレス描画では手描き風でなくマシンのシステムフォントで描かれ、警告が出る。CJKフォントの無いLinuxやDockerでは文字が四角になる。 - **Claude（claude.ai）やChatGPTで会話中に図を1枚見たいだけなら公式版**。ClaudeではAnthropic認証済みのコネクタとして掲載されており、サインインもインストールも不要。モデル向けの直接的な要素更新・ファイル保存ツールはないが、チェックポイントを使った再描画や要素削除には対応している。 - **Excalidraw+ MCPは公開ベータ**。Plus（料金ページの表示は1ユーザー月6ドル）のAPIキーが要り、ツールの名前や仕様は変わりうる。 ## Excalidraw MCPの3実装の違いと選び方 名前の似たプロジェクトが多いので、最初に3つを切り分けます。判断の軸は「どのクライアントで使うか」と「描いた図をファイルとして残すか」の2つです。 | 観点 | 公式 excalidraw-mcp | コミュニティ版 mcp-excalidraw-server | Excalidraw+ MCP | | ---------- | ------------------------ | ----------------------------- | ----------------- | | 最新版 | v0.3.2（2026-02-09） | 2.1.2（2026-10-04） | 公開ベータ | | 形態 | チャット内ウィジェット | ローカル常駐キャンバス | クラウドのワークスペース | | 主な利用先 | Claude・ChatGPT・VS Code | Claude Code・Codex・Cursor | Plus契約者のMCPクライアント | | モデルが使えるツール | 2（read\_me・create\_view） | 26 | 最大37（キーの権限次第） | | AIが図を見る | なし | describe・screenshot | take\_screenshot | | ファイル保存 | なし | .excalidraw をリポジトリへ | ワークスペースに保存 | | 認証・費用 | 不要・無料 | 不要・MIT | APIキー・Plus契約 | リポジトリのコードを読ませて構成図を描かせ、図もリポジトリに置きたいならコミュニティ版を選びます。会話の流れで図を見せたいだけなら公式版で十分です。Excalidraw+ MCPは、すでにPlusを契約していてクラウド上の図をAIに編集させたい場合に限って、ベータと承知で試す価値があります。 ### 公式 Excalidraw MCP はMCP Appsのチャット内ウィジェット Excalidraw組織の [excalidraw/excalidraw-mcp](https://github.com/excalidraw/excalidraw-mcp) は、プロンプトから手描き風の図をチャット内にストリーミング表示するMCPアプリです。READMEは対応クライアントとして「MCP Appsをサポートするクライアント（Claude、ChatGPT、VS Code、Gooseなど）」を挙げ、ホスト版 `https://mcp.excalidraw.com` を推奨しています（実際の接続先は `/mcp` で、ルートへのPOSTは308で転送されます）。最新リリースは v0.3.2（2026年2月9日）で、それ以降のリリースはありません。 2026年10月17日にホスト版へ認証なしで `tools/list` を送ったところ、返ってきたツールは5つで、そのうちモデルから呼べるのは `read_me`（要素フォーマットの説明）と `create_view`（図の描画）の2つでした。残る `export_to_excalidraw`・`save_checkpoint`・`read_checkpoint` はウィジェット側だけが使う設定（`visibility: ["app"]`）です。図をexcalidraw.comへ書き出すボタンはあっても、モデル向けのファイル保存ツールや直接的な要素更新ツールはありません。ただし、チェックポイントを復元し、削除マーカーと要素の再送を使って図を変更する経路はあります。 ### コミュニティ版 mcp-excalidraw-server は描いて見て直す作業台 yctimlin氏の [yctimlin/mcp\_excalidraw](https://github.com/yctimlin/mcp%5Fexcalidraw)（npmパッケージ名 `mcp-excalidraw-server`、MITライセンス、GitHubスター2,545＝2026年10月17日時点）は、ローカルで動くキャンバスサーバーをCLI・MCPサーバー・REST APIの3経路から操作します。[npmの公開履歴](https://www.npmjs.com/package/mcp-excalidraw-server)では 1.1.0（2026-07-06）→ 2.0.0（2026-08-19）→ 2.1.0（2026-10-03）→ 2.1.2（2026-10-04）と短期間に版が上がっています。GitHubのリリースタグはv2.1.0から付くようになりました。npmで配布されている版の確認は `npm view mcp-excalidraw-server version` で行います。 この記事で扱う手順の大半はこちらです。APIキーもアカウントも不要で、外へ出る通信はキャンバス画面がフォントをesm.shのCDNから読む分と、任意の `share` コマンドによるexcalidraw.comへのアップロードだけです。 ### Excalidraw+ MCP はPlusワークスペースへのリモート接続 [Excalidraw+ MCPのドキュメント](https://plus.excalidraw.com/docs/mcp)は2026年10月時点で「public beta」と明記し、ツール名・スキーマ・認証の挙動はまだ安定していないと断っています。エンドポイントは `https://api.excalidraw.com/api/v1/mcp`、トランスポートはStreamable HTTP、認証は `Authorization: Bearer ` のステートレス方式です。 [ツール一覧](https://plus.excalidraw.com/docs/mcp/tools)には37個が載っています。シーンの一覧・検索・編集（`search_scene_content`・`edit_scene_content`）、ノードと辺を渡すと配置と矢印の経路まで計算する `create_diagram`、スライド作成、描画結果を確かめる `take_screenshot`、ワークスペースやユーザーの管理まで並びます。APIキーの権限でツールが絞られる設計で、読み取り専用のキーなら書き込み系のツールは表示されません。AIに渡すキーは最小権限で別に発行するのが前提です。 ### 似た名前の excalidraw-mcp-server（debu-sinha氏）との取り違え npmには語順が逆の `excalidraw-mcp-server` もあり、こちらは別作者（Debu Sinha氏）のパッケージで、最新は 2.0.0（2026年2月8日）です。コミュニティ版 `mcp-excalidraw-server` も2026年8月19日に 2.0.0 になったため、「Excalidraw MCP v2.0」という情報はどちらの話か名前だけでは判別できません。ほかに `excalidraw-mcp`（1.0.0）や `mcp-excalidraw`（1.0.3）もあります。手順を写す前に、パッケージ名の語順を確かめてください。 ## コミュニティ版 v2.1のインストールと起動手順 前提はNode.js 20以上だけです。v1.1以降は描画系のコマンドとMCPサーバーがキャンバスサーバーを自動で起動するので、v1.0時代の「cloneしてビルドし、2つのターミナルで起動して絶対パスを書く」手順は、コントリビューター以外には不要です。 ### npxで動かすクイックスタート 次のコマンドは、2026年10月17日にmacOS・Node.js 26.5.0・2.1.2で実行して動作を確かめたものです。 ``` # キャンバスを起動（描画コマンドも自動で起動する） npx -y mcp-excalidraw-server start # 図形2つと矢印を作る（JSON配列を標準入力で渡す） echo '[ {"id":"api","type":"rectangle","x":100,"y":100,"width":160,"height":80,"text":"API Server"}, {"id":"db","type":"rectangle","x":400,"y":100,"width":160,"height":80,"text":"Database"}, {"type":"arrow","x":0,"y":0,"startElementId":"api","endElementId":"db","text":"SQL"} ]' | npx -y mcp-excalidraw-server add # エージェントに自分の図を見せる（テキスト要約とPNG） npx -y mcp-excalidraw-server describe npx -y mcp-excalidraw-server screenshot --out diagram.png # リポジトリ用に書き出す（出力先ディレクトリは先に作る） mkdir -p docs npx -y mcp-excalidraw-server export --out docs/architecture.excalidraw # 終わったら止める npx -y mcp-excalidraw-server stop ``` `add` の結果では、矢印の座標が図形の位置から自動で計算されていました（`"x": 268, "y": 140`、始点と終点に `api`・`db` が結び付く）。`describe` はIDと座標とラベルを1行ずつ返すので、エージェントはこれを読んで重なりやはみ出しを判断します。ブラウザで `http://127.0.0.1:3000` を開くと描かれる様子を見られますが、v2.1からは開かなくてもスクリーンショットが撮れます。 作成・更新・削除をまとめて当てる `apply` も使えます。複数の作成・更新・削除を1回のCLI呼び出しにまとめられるので、図の一括修正をエージェントに任せるときに向いています。 ``` echo '{"create":[{"type":"rectangle","x":100,"y":300,"width":160,"height":80,"text":"Cache"}], "update":[{"id":"db","set":{"backgroundColor":"#ffec99"}}], "delete":["tmp-1"]}' | npx -y mcp-excalidraw-server apply ``` キャンバスサーバーは既定で `127.0.0.1` にだけ待ち受けます（実測でもIPv4のループバックのみ）。`HOST=0.0.0.0` で外に開くとAPIに認証が無いまま公開されるので、社内で共有したい場合も前段にネットワーク側のアクセス制御を置いてください。 ### install-skillによるAgent Skillの配置 Claude CodeやCodex CLIのようにシェルを実行できるエージェントでは、MCPの設定よりAgent Skillを入れる経路が推奨されています。 ``` # スキルの置き場所を指定して配置（再実行で上書き更新） npx -y mcp-excalidraw-server install-skill --dir # 後方互換のショートカット npx -y mcp-excalidraw-server install-skill # ~/.claude/skills へ npx -y mcp-excalidraw-server install-skill --target codex # ~/.codex/skills へ ``` 実行すると `excalidraw-skill/` に `SKILL.md`・`references/cheatsheet.md`・`evals/evals.json` の3ファイルが置かれました。SKILL.mdの冒頭は「MCPツールが使えるならそれを優先し、無ければCLI、最後にREST」と指示しています。つまりスキルとMCP設定は二者択一ではなく、スキルを入れておけばどちらの環境でも同じ手順で描かせられます。スキルの仕組みは[Claude Skillsの解説](/tech/details/9396/)、Codex側の配置は[Codex Skillsの解説](/tech/details/10181/)が詳しいです。 ## v2.0・v2.1で変わった点とv1.1からの移行 2026年7月に1.1.0でCLI中心の構成になってから、わずか3か月で2回の大きな更新が入りました。v1.1の手順を書いた記事やブログはまだ多く、次の4点が食い違いの原因になります。 ### v2.0：Node.js 20必須とMCP 2026-07-28版への対応 v2.0の唯一の破壊的変更は、必要なNode.jsが18から20へ上がったことです。MCPのTypeScript SDK v2が下限を引き上げたためで、npmの `engines` も `"node": ">=20.0.0"` になっています。既存のMCPクライアント設定はそのまま動きます。 同時に、MCP仕様の2026-07-28版（ハンドシェイク無しでツールを呼べるステートレス方式、`server/discover`）に対応し、従来の `initialize` で始めるクライアントとも互換を保っています。実測では `initialize` で `protocolVersion: "2025-06-18"` を送ると同じ版で応答し、`tools/list` で26ツールが返りました。仕様の変更点は[MCP仕様2026-07-28版の解説](/tech/details/18245/)にまとめています。 ### v2.0：excalidraw.com・Obsidian互換のファイル書き出し v1.x までは、書き出した `.excalidraw` をexcalidraw.comやObsidianのExcalidrawプラグインで開くとラベルが消えることがありました。v2.0からは図形と矢印のラベルが本来の「結び付いたテキスト要素」として保存されます。実測でも、図形2つと矢印1本（ラベル付き）を書き出すと要素数は6（ラベル3つが独立した要素になる）でした。 書き出しはバイト単位で安定し、図を変えずに書き出し直してもGitに差分が出ません。出力先の拡張子を `.excalidraw.md` にするとObsidianのプラグイン形式で書き出せるので、Vaultに直接置けます。ObsidianとClaude Codeの組み合わせは[Claude CodeとObsidianの連携方法](/tech/details/13174/)で扱っています。 ### v2.1：スクリーンショットと画像書き出しのヘッドレス対応 v2.1の目玉はヘッドレス描画です。`screenshot`・`export_to_image`・`get_canvas_screenshot` がキャンバスサーバー内で描画されるようになり、ブラウザのタブを開いていなくても動きます。v1.1では「スクリーンショットはタブが必要（終了コード4）」でしたが、2.1.2で終了コード4が出るのは `mermaid` と `screenshot --renderer browser` だけです。 実測では、タブを一度も開かずに `screenshot` が480×100ピクセルのPNGを返しました。初回はレンダラーの読み込みで約15秒かかり、2回目以降はnpxの起動込みで1.6〜2.2秒でした。図を変えずに2回撮ったPNGはMD5が一致し、決定的に同じ画像になります。さらに `render docs/arch.excalidraw --out docs/arch.png` はキャンバスサーバー無しでファイルからPNGを作るので、CIでコミット済みの図から画像を作り直す用途に使えます。 ### npm版2.1.2の永続化未対応と再起動時のデータ消失 READMEには、環境変数 `EXCALIDRAW_DATA_DIR` を設定すると再起動後も図とスナップショットが復元される「durable canvas state」が載っています。ただしこれは2026年10月9日にmainブランチへ入った機能で、npmの2.1.2のパッケージを展開して検索しても `EXCALIDRAW_DATA_DIR` は1件もありませんでした。npx で使う限り、キャンバスはまだインメモリで、サーバーを止めると図は消えます。作業の区切りごとに `export` してファイルに保存してください。2.1.2のスナップショットはメモリ上の一時保存で、サーバー再起動後には復元できません。 ## 日本語ラベルを使うときの注意（2.1.2実測） 日本語で図を描かせる人がまず当たるのがフォントです。ヘッドレス描画に同梱されているフォントはExcalifont・Virgil・Cascadia Code・Liberation Sansで、どれもラテン文字向けです。READMEも「CJK（中国語・日本語・韓国語）と絵文字はマシンのフォントにフォールバックする」と書いています。 実際に、ラベルを「データベース」にした図形を含むシーンで `screenshot` を実行すると、`warning: non-Latin text detected: system fonts were used, so output may differ across machines` という警告が出ました。macOSでは文字自体は描かれましたが、英字ラベルの手描き風フォントとは違う、通常のゴシック体になります。同じマシンで撮り直したPNGはMD5が一致しましたが、フォントの違うマシン間では、日本語ラベルを含む図のPNGがバイト単位まで一致するとは限りません。 CJKフォントの入っていないLinuxやDockerでは、READMEのトラブルシューティングどおり文字が四角（豆腐）になります。CIで画像を作るなら、ランナーやコンテナに日本語フォント（Debian・Ubuntuなら `fonts-noto-cjk` パッケージ）を入れておきます。図の見た目まで揃えたい場合は、ラベルを英語にしてExcalifontで描かせ、日本語の説明は図の外に書くほうが確実です。 ## Claude Code・Claude Desktop・Cursor・Codex CLIの設定 MCPサーバーとして登録する場合、どのクライアントでも起動コマンドは `npx -y mcp-excalidraw-server` です。既定値のままなら環境変数も絶対パスも要りません。MCPそのものの仕組みは[MCP（Model Context Protocol）とは](/tech/details/5736/)で解説しています。 ### Claude Code・Codex CLIへの1コマンド登録 ``` # Claude Code claude mcp add excalidraw --scope user -- npx -y mcp-excalidraw-server claude mcp list # 登録を解除するときだけ実行 # claude mcp remove excalidraw # Codex CLI codex mcp add excalidraw -- npx -y mcp-excalidraw-server codex mcp list ``` Claude Codeの `--scope user` は全プロジェクトで使える個人設定で、`--scope project` にするとプロジェクト直下の `.mcp.json` に書かれてチームで共有されます。図をリポジトリの資産として運用するならprojectスコープが合います。 ### Claude Desktop・Cursor・OpenCode・Antigravityの設定ファイル | クライアント | 設定ファイル | | ----------------------- | ------------------------------------------------------------------ | | Claude Desktop（macOS） | \~/Library/Application Support/Claude/claude\_desktop\_config.json | | Claude Desktop（Windows） | %APPDATA%\\Claude\\claude\_desktop\_config.json | | Claude Desktop（Linux） | \~/.config/Claude/claude\_desktop\_config.json | | Cursor | .cursor/mcp.json（全体は \~/.cursor/mcp.json） | | OpenCode | \~/.config/opencode/opencode.json | | Antigravity | \~/.gemini/antigravity/mcp\_config.json | Claude Desktop・Cursor・Antigravityは同じJSONの形です。 ``` { "mcpServers": { "excalidraw": { "command": "npx", "args": ["-y", "mcp-excalidraw-server"] } } } ``` OpenCodeだけはスキーマが違い、`type` と配列形式のコマンドを取ります。 ``` { "$schema": "https://opencode.ai/config.json", "mcp": { "excalidraw": { "type": "local", "command": ["npx", "-y", "mcp-excalidraw-server"], "enabled": true } } } ``` ### Dockerで動かすときのhost.docker.internal MCPサーバーのイメージ `ghcr.io/yctimlin/mcp_excalidraw:latest` はフロントエンドを含まず、`EXCALIDRAW_NO_AUTOSTART=1` が設定済みです。キャンバスは別のコンテナで起動します。 ``` docker run -d -p 3000:3000 --name mcp-excalidraw-canvas \ ghcr.io/yctimlin/mcp_excalidraw-canvas:latest claude mcp add excalidraw --scope user \ -- docker run -i --rm \ -e EXPRESS_SERVER_URL=http://host.docker.internal:3000 \ ghcr.io/yctimlin/mcp_excalidraw:latest ``` Linuxでは `host.docker.internal` が既定で名前解決されないため、`--add-host=host.docker.internal:host-gateway` を付けるか `172.17.0.1` を直接指定します。macOS向けの設定をLinuxへ移した場合は、まずこのホスト名の名前解決を確認してください。 ## 公式版をClaudeとChatGPTで使う手順 公式版はローカルに何も入れずに使えます。Claude（Web版・デスクトップ版）では、[Claudeのコネクタ一覧](https://claude.com/marketplace/connectors/excalidraw-app-demo)にExcalidrawが「Anthropic verified」として2026年2月から掲載されており、「Add to Claude」から追加できます。サインインは不要で、接続先は `https://mcp.excalidraw.com/mcp` です。一覧から追加できない環境では、設定のコネクタで「カスタムコネクタを追加」を選び、同じURLを入れても動きます。ChatGPTやVS Codeでは、カスタムMCPやコネクタを追加する画面にこのURLを登録します（画面の呼び名はアプリごとに違います）。 接続したら「ユーザーがAPIサーバーに接続し、APIサーバーがデータベースと通信する構成図を描いて」のように頼むと、要素が1つずつ描き足される様子がチャット内に表示されます。ウィジェット上で手直ししたり、excalidraw.comで開いて編集を続けたりできます。 ローカルで動かしたい場合は、GitHubのReleasesにある `excalidraw-mcp-app.mcpb` をダブルクリックしてClaude Desktopに入れるか、ソースからビルドします。自前のホストに置きたい場合、READMEは「リポジトリをフォークしてVercelにインポートするだけ、環境変数は不要」と案内しています。 ウィジェットを表示できることが前提の作りです。図の修正は、チェックポイント（v0.3.0で追加）を復元して削除マーカーと要素を送り直す宣言的な方式で、要素を1つ指定して更新する専用ツールや、モデルがファイルへ保存するツールはありません。ターミナルのエージェントで図をリポジトリに残すならコミュニティ版を選んでください。 ## Excalidraw+ MCPの接続設定 前提は、Excalidraw Plusのワークスペースと、ワークスペース設定で発行したAPIキーです。[料金ページ](https://plus.excalidraw.com/pricing)にはPlusの料金が1ユーザー月額換算6ドルと表示されています。請求周期ごとの適用額は契約画面で確認してください。14日間の無料試用があります。キーには個人用とワークスペース用があり、ドキュメントは「自分の代わりに動くエージェントには個人用キー、共有の連携にはワークスペース用キー」を勧めています。 Claude Codeではプロジェクトの `.mcp.json` に次のように書きます。 ``` { "mcpServers": { "excalidraw": { "type": "http", "url": "https://api.excalidraw.com/api/v1/mcp", "headers": { "Authorization": "Bearer " } } } } ``` Codexは `config.toml` に書き、キーは環境変数から渡します。キーを設定ファイルに直書きしないで済むので、リポジトリで共有する設定にはこちらの形が向いています。 ``` [mcp_servers.excalidraw] url = "https://api.excalidraw.com/api/v1/mcp" env_http_headers = { Authorization = "EXCALIDRAW_API_KEY" } ``` 次のコマンドは設定ファイルに書かず、Codexを起動するシェルで実行します。 ``` export EXCALIDRAW_API_KEY="Bearer " ``` つながらないときは、401ならAuthorizationヘッダーの欠落か誤り、ツールが見えないならキーの権限不足、405なら `POST /api/v1/mcp` 以外で呼んでいる（ステートレスなのでPOSTだけ）と、ドキュメントのトラブルシューティングに整理されています。 ## 26ツールの分類と「描く→見る→直す」ループ 2.1.2に `tools/list` を送って数えた26個は、READMEの分類と一致しました。 - **要素の操作（7）**：`create_element`・`get_element`・`update_element`・`delete_element`・`query_elements`・`batch_create_elements`・`duplicate_elements` - **レイアウト（6）**：`align_elements`・`distribute_elements`・`group_elements`・`ungroup_elements`・`lock_elements`・`unlock_elements` - **シーンの認識（2）**：`describe_scene`・`get_canvas_screenshot` - **ファイル入出力（5）**：`export_scene`・`import_scene`・`export_to_image`・`export_to_excalidraw_url`・`create_from_mermaid` - **状態管理（3）**：`clear_canvas`・`snapshot_scene`・`restore_snapshot` - **その他（3）**：`set_viewport`・`read_diagram_guide`・`get_resource` 効いているのはシーンの認識の2つです。`describe_scene` がIDと座標とラベルと接続関係をテキストで返し、`get_canvas_screenshot` が描画結果の画像を返すので、エージェントはラベルのはみ出しや矢印の交差を自分で見つけ、要素を指定して直せます。公式版との違いはここに尽きます。 実務では、図を `export_scene` で `.excalidraw` としてリポジトリに書き出し、構成が変わったら `import_scene` で読み戻して直す流れになります。作業中の一時退避は `snapshot_scene` と `restore_snapshot` です。MCPもCLIも使わないアプリからは、キャンバスサーバーのREST API（例：`GET /api/elements`）を直接呼べます。こうしたエージェントの組み込みを社内システムで設計する場合は、[AIエージェント開発の支援](https://www.issoh.co.jp/service/ai/agent/)も行っています。 ## Mermaidと比べてExcalidraw MCPを選ばない場面 図の変更をプルリクエストで差分レビューしたいなら、Excalidraw MCPは向きません。`.excalidraw` は座標やスタイルを持つJSONです。v2.0で書き出しが安定したとはいえ、行の差分には座標やスタイルの変化も混ざるため、ノードの追加や接続の変更を追うにはMermaidより多くの行を読む必要があります。レビューで中身を読ませたい図は、[Mermaid記法](/tech/details/3374/)のテキスト定義が明確に有利です。VS Codeで書いてプレビューする運用は[VSCodeでMermaidを使う方法](/tech/details/6583/)にまとめています。 生成するトークン量でもMermaidが有利です。数行で済む図に対して、Excalidrawは要素ごとに座標・サイズ・接続を指定します。単純なフローチャートを大量に作るなら、Excalidraw MCPを選ぶ理由はありません。 逆にExcalidraw MCPを選ぶのは、配置や余白の見栄えが成果物の価値を決める図です。設計レビューや提案資料に載せる構成の概要図なら、AIに下図を描かせたあと、要素単位で位置や余白を調整できます。両方を使うなら、テキストで確定できる図はMermaid（`create_from_mermaid` でキャンバスに取り込める。ただしブラウザのタブが必要）、人が配置を調整したい図はExcalidrawと分けるのが現実的です。構成図そのものの書き方は[アーキテクチャ図の書き方とC4モデル](/tech/details/4024/)を参照してください。 ## 頻出エラーと復旧手順 CLIは終了コードで原因を切り分けられます。0が正常、1がエラー、2が使い方の誤り、3がキャンバスに届かない、4がブラウザのタブが必要、です。 - **終了コード3で「did not become healthy within 8000ms」**：キャンバスの起動を待って8秒で諦めた状態です。実測では、ポートを別のアプリ（Next.jsの開発サーバー）が使っていたときにこのエラーになり、`/health` にはそのアプリの404ページが返っていました。`lsof -nP -iTCP:3000 -sTCP:LISTEN` で占有しているプロセスを確かめ、止めるか `PORT` と `EXPRESS_SERVER_URL` を同じ別番号にそろえます。 - **終了コード3（そのほか）**：`status` のような確認系のコマンドは自動起動しません。`EXCALIDRAW_NO_AUTOSTART=1` を設定している場合や、`EXPRESS_SERVER_URL` がループバック以外を指している場合も同じです。`start` を明示的に実行します。 - **終了コード4**：2.1.2では `mermaid` と `screenshot --renderer browser` だけが出します。`http://127.0.0.1:3000` をブラウザで開いて再実行してください。 - **起動しない（Node 18）**：v2.0からNode.js 20以上が必須です。`node -v` で確かめます。 - **PNGの日本語が四角になる**：実行マシンにCJKフォントがありません。上の日本語ラベルの章を参照してください。 - **再起動したら図が消えた**：npmの2.1.2はインメモリで、仕様どおりの挙動です。`export` でファイルに保存します。2.1.2ではスナップショットも再起動で失われます。 接続を確かめるときは、キャンバスのヘルスチェックから順に進めます。ヘルスチェックのパスは `/health` で、`/api/health` は404になります（実測）。 ``` curl http://127.0.0.1:3000/health npx -y mcp-excalidraw-server status npx -y mcp-excalidraw-server add --one '{"type":"rectangle","x":100,"y":100,"width":300,"height":200}' npx -y mcp-excalidraw-server describe ``` 正常なら `/health` は `{"status":"healthy",...,"renderers":{"node":true,...}}` を返します。`"node": true` がヘッドレス描画を使える印です。 ## よくある質問 ### Excalidraw MCPはClaude Codeで使えますか？ 使えます。コミュニティ版 `mcp-excalidraw-server` を `claude mcp add excalidraw --scope user -- npx -y mcp-excalidraw-server` で登録するか、`install-skill` でAgent Skillを入れます。公式版はチャット内ウィジェットとして作られており、モデルが使えるツールが2つしかないため、Claude Codeで図を保存したり直したりする用途には向きません。 ### Codexで使うにはどうすればいいですか？ `codex mcp add excalidraw -- npx -y mcp-excalidraw-server` でMCPサーバーとして登録するか、`npx -y mcp-excalidraw-server install-skill --target codex` で `~/.codex/skills` にスキルを入れます。スキルはMCPツールがあればそれを使い、無ければCLIを使うよう書かれているので、両方入れても問題ありません。 ### APIキーやアカウントは必要ですか？ コミュニティ版と公式版は不要です。コミュニティ版はローカルで完結し、外部への通信はキャンバス画面のフォント読み込みと任意の `share` だけです。Excalidraw+ MCPだけは、Excalidraw Plus（料金ページの表示は1ユーザー月6ドル）で発行したAPIキーが必要です。 ### shareで作ったリンクは他人に見られませんか？ `share` はアップロード前にシーンをAES-GCMでローカル暗号化し、復号鍵はURLの `#` 以降（フラグメント）にだけ入ります。フラグメントはexcalidraw.comのサーバーに送られません。ただし完全なリンクを受け取った人は誰でも図を見られるので、リンクを渡した範囲がそのまま公開範囲になります。 ### 公式版とコミュニティ版を両方入れても大丈夫ですか？ 併存できます。公式版はリモートのMCPアプリ、コミュニティ版はローカルのstdioサーバーで、接続先が別です。登録名が重ならないように分け、普段使わないほうを無効にしておくと、モデルに見えるツール一覧が短く保てます。 ## 関連記事 - [Excalidrawの使い方とDockerセルフホスト手順｜Reactへの埋め込みまで](/tech/details/17487/) - [MCP（Model Context Protocol）とは？AIと外部ツールをつなぐ標準規格の仕組みをわかりやすく解説](/tech/details/5736/) - [Claude Skillsとは？SKILL.mdの書き方とclaude.ai・Claude Code・APIでの使い方【2026年10月】](/tech/details/9396/) - [Codex Skillsとは？できること・SKILL.mdの作り方と配置場所を解説【2026年最新】](/tech/details/10181/) - [Mermaid記法の使い方｜無料のLive Editor（mermaid.live）でフローチャート・シーケンス図を作成](/tech/details/3374/) --- 出典: [Excalidraw MCPの導入と使い方｜Claude Code・Cursor・Codex設定と3実装の選び方【v2.1対応】]()（株式会社一創）