mcp-excalidraw

Name: mcp-excalidraw
Author: yctimlin

ローカル

mcp-excalidraw-landing.vercel.app開発ツール2.6k6 日前に更新

リポジトリ公式サイト

mcp-excalidraw について

mcp-excalidraw は、ライブの Excalidraw キャンバス上で図の作成・編集・エクスポートを行う MCP サーバー、コマンドライン、エージェントスキルです。コーディングエージェントがスクリーンショットで描画結果を確認し、.excalidraw ファイルをコードと一緒に保存できます。API キーは不要です。

主な機能

0126 個の MCP ツールによる要素単位の作成・読み取り・更新・削除
02コマンドラインと REST API による呼び出し
03スクリーンショットと構造化された説明によるキャンバスの確認
04Mermaid 変換と .excalidraw のインポート・エクスポート
05CI や Docker で使えるヘッドレスレンダリング
06名前付きスナップショットとロールバック

活用シーン

01コーディングエージェントにサービスのアーキテクチャ図を描かせて更新する
02.excalidraw 図をコードと一緒にリポジトリへコミットする
03CI パイプラインでコミット済みの図をオフラインでレンダリングする

MCP 対応

本プロジェクトは stdio 経由の MCP サーバーとして動作し、Claude Desktop や Cursor などの MCP クライアントに 26 個の描画ツールを提供します。

#mcp-excalidraw #excalidraw #drawing-api

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定

{
  "mcpServers": {
    "mcp_excalidraw": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "build"
      ]
    }
  }
}

起動コマンドdocker run -i --rm build

ローカルサーバーにはマシン上の実行環境（Node.js 18 以上など）が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ

ocibuildstdio

ツール

ツール一覧はまだ取得されていません

ローカルサーバーのツールはマシン上で起動して初めて取得できます。メンテナーはまだツール一覧を提供していません。

詳細

Excalidraw MCP サーバー、CLI、エージェントスキル

mcp-excalidraw-server を使うと、AI エージェントがライブの Excalidraw キャンバスに描画し、内容を確認して調整し、リポジトリに保存できます。エージェントはアーキテクチャ図やフローチャートをプログラムで作成し、スクリーンショットで自分の作業を確認し、レイアウトの問題を修正して、コードと一緒にコミットできる .excalidraw ファイルとしてエクスポートします。

1 つのキャンバスを操作する 3 つの方法：

エージェントスキル + CLI — コーディングエージェント（Claude Code、Codex CLI、Cursor、OpenCode）に推奨：npx -y mcp-excalidraw-server <command>。設定不要で、キャンバスを自動起動し、組み合わせ可能な JSON の入出力に対応します。
MCP サーバー — あらゆる Model Context Protocol クライアント（Claude Desktop、Cursor、Codex CLI、Antigravity など）向けに、stdio 経由で 26 個のツールを提供します。MCP 2026-07-28（server/discover、リクエストごとの _meta エンベロープ、ハンドシェイクなしのツール呼び出し）に対応し、initialize で接続を開始する 2025 年時代のクライアントとの互換性も維持します。
REST API — LangChain やカスタムフレームワーク向けのプレーンな HTTP です。

描画の中核はローカルで動作します（Node ≥ 20、MIT ライセンス）。API キーやアカウントは不要です。Mermaid の変換はローカルのブラウザーキャンバスで実行されます。share はオプションで、暗号化されたシーンを excalidraw.com にアップロードします。キャンバスページは esm.sh CDN から Excalidraw のフォントを読み込みます。

デモ

MCP 経由でライブの Excalidraw キャンバスにアーキテクチャ図を描く AI エージェント

AI エージェントが 1 つのプロンプトから完全なアーキテクチャ図を作成します（4 倍速）。YouTube で動画全編を見る

デモ
概要
公式 Excalidraw MCP との違い
新機能
インストール
エージェントスキル
CLI リファレンス
ヘッドレスレンダリング
MCP クライアントの設定
MCP ツール（全 26 個）
クイックスタート（ソースから／Docker）
テスト
FAQ
トラブルシューティング
既知の問題／TODO
開発
ライセンス

概要

エージェントに 「このサービスのアーキテクチャを描いて」 と頼むと、一度きりの画像ではなく、編集可能な実際の Excalidraw 図を作成します。エージェントは個々の要素を照会、スクリーンショット撮影、更新できるため、ラベルが収まり、要素が重ならず、矢印がきれいに経路を通るまで繰り返し調整します。その後、結果を .excalidraw ファイルとしてエクスポートします。このファイルはリポジトリ内に保存され、コードの変更に合わせて更新できます。

内部では、1 つの製品が 2 つのプロセスで構成されています。

キャンバスサーバー：Excalidraw の Web UI + REST API + WebSocket によるリアルタイム同期（デフォルトは http://127.0.0.1:3000）
お好みの薄いフロントエンド：CLI、MCP stdio サーバー、生の HTTP のいずれも、同じキャンバスを操作します

v1.1 以降、キャンバスサーバーは自動起動します。キャンバスを操作する CLI コマンドと、起動時の MCP サーバーは、リッスン中のサーバーがなければ自動的にサーバーを起動します。status は現在のサーバー状態を確認するだけです。自動起動を無効にするには EXCALIDRAW_NO_AUTOSTART=1 を設定します。

公式 Excalidraw MCP との違い

Excalidraw には公式 MCPがあります。これは、1 つのプロンプトから図をチャット内にストリーミング表示するチャットウィジェットです（モデルにはフォーマットのリファレンスと create_view の 2 つのツールが提供されます）。Claude や ChatGPT で「猫を描いて」と頼む用途には最適です。一方、私たちが解決するのは別の課題です。コーディングエージェントに、永続的なキャンバス作業環境を提供します。

	公式 Excalidraw MCP	このプロジェクト
アプローチ	プロンプトを入力し、図を出力（1 回限りのウィジェット）	要素単位のプログラムによる制御（CLI ＋ 26 個の MCP ツール）
状態	チャットウィジェット内のチェックポイント	リアルタイム同期と、任意で再起動後も保持されるチェックポイントを備えたライブキャンバス
要素の CRUD	削除マーカーを付けて宣言的に再送信	要素ごとの作成／読み取り／更新／削除に完全対応
AI からのキャンバスの見え方	いいえ	`describe`（構造化テキスト）＋ `screenshot`（画像）
反復的な調整	チェックポイントから再生成	描画 → 確認 → 調整 → 再確認を要素ごとに実行
レイアウトツール	なし	整列、分布、グループ化／グループ解除、ロック、複製
ファイル I/O	モデル向けのエクスポートなし	`.excalidraw` のエクスポート／インポート — リポジトリのアーティファクトとして図を保存
スナップショットとロールバック	ウィジェット側のチェックポイント	サーバー側の名前付きスナップショット
Mermaid 変換	なし	`mermaid` ／ `create_from_mermaid`
共有可能な URL	ウィジェットのみ	`share` ／ `export_to_excalidraw_url`
ビューポート制御	カメラアニメーション	`set_viewport`（すべての要素または選択した要素に合わせてズーム、1 つの要素を中央に表示、手動ズーム）
MCP なしでの動作	いいえ	はい — CLI ＋エージェントスキル＋ REST API
マルチエージェント	単一のチャット	複数のエージェントが同じキャンバスを同時に操作

要するに — 公式 MCP はチャット内に Excalidraw の図を表示します。このプロジェクトは、コーディングエージェントに、描画、確認、調整、リポジトリへのコミットができるキャンバスを備えた、完全な Excalidraw 作業環境を提供します。

インストール

前提条件は Node.js ≥ 20 のみです。

最も簡単な方法：エージェントにインストールさせる

以下をコーディングエージェントにコピーしてください。エージェントがすでに利用方法を把握しているプロジェクトまたはグローバルのスキルディレクトリにポータブルなスキルをインストールし、テスト図を描画して動作を確認します。

Install the Excalidraw canvas toolkit so you can draw diagrams for me:

1. Choose the right skill directory for this agent and scope (project or global).
2. Run: npx -y mcp-excalidraw-server install-skill --dir <that-skills-directory>
3. Read the installed excalidraw-skill/SKILL.md so you know the drawing workflow.
4. Start the canvas with: npx -y mcp-excalidraw-server start
   then tell me I can open http://127.0.0.1:3000 to watch you draw (optional).
5. Draw a small test diagram — two labeled boxes connected by an arrow — take a
   screenshot, and show me the result to confirm everything works.

手動インストール

対象	インストール方法	その後
最新のコーディングエージェント	`npx -y mcp-excalidraw-server install-skill --dir <skills-root>`	エージェントにプロジェクト単位かグローバルか、およびスキルのルートを選ばせます
Claude Code のショートカット	`npx -y mcp-excalidraw-server install-skill`	後方互換性のため、`~/.claude/skills` にインストールします
Codex のショートカット	`npx -y mcp-excalidraw-server install-skill --target codex`	後方互換性のため、`~/.codex/skills` にインストールします
MCP クライアントのユーザー（Claude Desktop、Cursor など）	以下の npx 設定を追加します	MCP クライアントの設定を参照してください
CLI ユーザー／スクリプト作成者	不要 — `npx -y mcp-excalidraw-server <command>`	CLI リファレンスを参照してください
コントリビューター／ソースから利用する場合	`git clone` + `npm ci` + `npm run build`	クイックスタート（ソースから／Docker）を参照してください

個別のサーバー設定は不要です。描画コマンドを実行すると、ローカルのキャンバスサーバーが http://127.0.0.1:3000 で自動的に起動します。

60 秒で始めるクイックスタート（CLI）

クローンも設定も不要です：

# start the canvas (drawing commands auto-start it too) and open it
npx -y mcp-excalidraw-server start
open http://127.0.0.1:3000   # optional: watch live (only mermaid needs the tab)

# draw something
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","x":0,"y":0,"startElementId":"api","endElementId":"db","text":"SQL"}
]' | npx -y mcp-excalidraw-server add

# let your agent see its work
npx -y mcp-excalidraw-server describe
npx -y mcp-excalidraw-server screenshot --out diagram.png

# diagrams as repo artifacts
mkdir -p docs
npx -y mcp-excalidraw-server export --out docs/architecture.excalidraw

# or straight into an Obsidian vault (.md extension → Obsidian Excalidraw plugin format)
npx -y mcp-excalidraw-server export --out ~/vault/diagrams/architecture.excalidraw.md

エージェントにプレイブック全体を渡します：

npx -y mcp-excalidraw-server install-skill --dir <skills-root>
npx -y mcp-excalidraw-server install-skill --print-source  # inspect bundled source path

セキュリティに関する注意： キャンバスサーバーはデフォルトで 127.0.0.1 のみにバインドされます。ネットワークインターフェース（HOST=0.0.0.0）で公開する場合は、ネットワークレベルのアクセス制御を前段に設けてください。API には認証機能が組み込まれていません。

エージェントスキル

skills/excalidraw-skill/ にあるスキルでは、レイアウトの計画、スクリーンショットで確認して修正する品質向上ループ、矢印の経路設定、アンチパターン、スナップショット、ファイルの入出力など、ワークフロー全体をエージェントに教えます。CLI（推奨、設定不要）、MCP ツール（設定済みの場合）、または REST API を直接使う方法の順に利用できます。

npx -y mcp-excalidraw-server install-skill --dir <skills-root>

このコマンドは、同梱されている excalidraw-skill/ ディレクトリを <skills-root>/excalidraw-skill にコピーします。ルートをプロジェクト単位にするかグローバルにするかは、エージェントに選ばせてください。install-skill を再実行すると、その場でアップグレードされます。対象ディレクトリは置き換えられるため、上流で削除されたファイルが残ることはありません。

このスキルが役立つ場面：

コード成果物としての図：.excalidraw ファイルをリポジトリにエクスポートしてコミットし、アーキテクチャの変更時に再インポートして調整できます。
Obsidian の保管庫：.excalidraw.md 拡張子でエクスポートすると、Obsidian Excalidraw プラグインでファイルをネイティブに開けます。互換モードの警告が表示されず、ブロック参照と同期も機能します。import は、プレーン形式と lz-string 圧縮形式の両方の保管庫ファイルを読み戻します。
自己検証する図：エージェントは自分の作業をスクリーンショットで確認し、完了と判断する前に、テキストの切れや重なりを修正します。
MCP を使わない環境：CI ジョブ、通常のシェル、フレームワークでも、CLI を通じて同じ機能を利用できます。

CLI リファレンス

npx -y mcp-excalidraw-server <command> または（npm i -g mcp-excalidraw-server の実行後）excalidraw-canvas <command>。

規約：JSON の結果は標準出力に出力されます。ただし、describe は設計上プレーンテキストで、--out を省略した場合の生コンテンツ出力も例外です（export はシーン JSON を、screenshot --format svg は SVG を出力します）。診断メッセージは標準エラー出力に出力されます。終了コード：0 正常、1 エラー、2 使用方法の誤り、3 キャンバスに到達できない、4 ブラウザータブが必要（mermaid と screenshot --renderer browser のみ）。キャンバスの URL は EXPRESS_SERVER_URL または --url から取得します。キャンバスを操作するコマンドはサーバーを自動起動します。status は現在の状態のみを報告します。明示的な start は EXCALIDRAW_NO_AUTOSTART=1 のオプトアウト設定より優先されます（これは自動起動ではなく、ユーザーの意図によるものです）。

コマンド	説明
`start` / `stop` / `status`	キャンバスサーバーを管理します（デタッチ方式。`stop` はシグナル送信前に `/health` を介して稼働中のサーバーの同一性を確認します）
`add [file\|-]`	JSON 配列から要素をまとめて作成します（ファイルまたは標準入力）。単一要素には `--one '{...}'` を使用します
`apply [file\|-]`	複数の操作を 1 回の呼び出しで適用するパッチ：`{"create":[...],"update":[{"id":"a","set":{...}}],"delete":["id"]}`
`get <id>` / `delete <id...>`	要素を読み取る／削除します
`update <id> --set '{...}'`	要素を更新します
`query`	`--type`、`--bbox x0,y0,x1,y1`、`--filter k=v`（型指定、ネストされたキー）、`--filter-json '{...}'`
`describe`	AI が読み取れるシーンの概要（プレーンテキスト）
`screenshot`	キャンバスをヘッドレスでレンダリングします（ブラウザータブ不要）：`--out f.png\|f.svg`、`--format png\|svg`、`--scale 1-4`、`--dark`、`--padding N`、`--no-background`、`--ids a,b`、`--frame <id>`、`--no-embed-fonts`、`--embed-scene`（編集可能な PNG）。`--renderer browser` を指定すると、開いているタブを使用します
`render [file\|-]`	`.excalidraw`／`.excalidraw.md`／シーンが埋め込まれた PNG ファイルをオフラインで PNG／SVG にレンダリングします。キャンバスサーバーは不要で、`screenshot` と同じフラグを使用します
`export [--out f.excalidraw] [--format json\|obsidian]` / `import [file\|-] [--replace]`	シーンファイルの入出力です。`.md` の出力パスには Obsidian の `.excalidraw.md` 形式で書き込みます。`import` はシーンが埋め込まれた PNG も読み取ります
`mermaid [file\|-]`	Mermaid → キャンバス（ブラウザータブが必要）
`snapshot save\|list\|restore <name>`	名前付きスナップショット
`arrange align\|distribute\|group\|ungroup\|lock\|unlock\|duplicate`	レイアウト操作（`--ids a,b,c`、`--to left\|horizontal\|...`）
`share`	暗号化してアップロードし、共有可能な excalidraw.com URL を取得します
`clear --yes`	キャンバスを消去します
`install-skill [--dir <skills-root>]`	ポータブルなエージェントスキルをインストールします

ラベルと矢印のバインドでは、CLI のどこでもエージェントに扱いやすい形式を使用します。任意の図形に "text"、矢印に "startElementId"／"endElementId" を指定すると、自動的に正規化されます。ネイティブフレームを使うには、"name" を指定した "type":"frame" 要素を追加し、その子要素に "frameId" を設定します。

ヘッドレスレンダリング

v2.1 以降、screenshot、export_to_image、get_canvas_screenshot はブラウザーなしでレンダリングします。キャンバスサーバー内では、キャンバスタブ独自のコード（ラベルのサイズ調整、折り返し、中央揃え、デフォルト値）でシーンを準備し、Excalidraw 独自の exportToSvg で Node 上に描画します（小規模な jsdom シムが想定される DOM を提供し、テキストの幅は同梱フォントの実際のグリフ幅で測定します）。resvg が SVG を PNG にラスタライズします。出力は Excalidraw のキャンバスが描画するものと同じです。ブラウザーでエクスポートした場合と同じ SVG 構造で、テキストのずれは半ピクセル以内です。また、決定論的です。同じシーンはバイト単位で同一の SVG と PNG にレンダリングされるため、コミット済みの画像に差分が生じません。

フォント：Excalifont、Virgil、Cascadia Code、Liberation Sans は TTF として assets/fonts に同梱されています（すべて SIL OFL 1.1。assets/fonts/LICENSES.md を参照）。SVG には使用する書体が埋め込まれるため、ブラウザー、GitHub、エディターで正しく表示されます。Nunito、Lilita One、Comic Shanns は現時点では最も近い同梱フォントでレンダリングされます。その他の文字体系（CJK、絵文字）のテキストは、マシンのフォントにフォールバックし、警告が表示されます。
オプション（CLI フラグ／REST ボディ／MCP パラメーター）：background、dark、scale 1～4（PNG）、padding、一部の要素をレンダリングする elementIds または frameId、embedFonts、embedScene（PNG のみ。デフォルトは false）。EXCALIDRAW_RENDER_MAX_DIM（デフォルトは 8192）で PNG の最大辺を制限します。
--renderer browser を指定すると、開いているキャンバスタブにレンダリングを依頼します（v2.1 より前の方式）。別の結果を確認するのに便利ですが、処理が遅く、最初にタブの未同期の編集内容は破棄されます。
オフライン：render docs/arch.excalidraw --out docs/arch.png はキャンバスサーバーを必要としません。コミット済みの図の隣に画像を保存する CI ジョブに最適です。
引き続きブラウザーが必要な機能：Mermaid 変換（mermaid、create_from_mermaid）と set_viewport。

レンダラーバンドルは npm run build:server（dist/render/excalidraw-node.mjs）でビルドされます。npm run test:render では、ブラウザーなしで動作をテストできます。

MCP クライアントの設定

MCP サーバーは stdio 経由で動作します。v1.1 以降、最も簡単な設定は npx です。クローンや絶対パスは不要で、キャンバスも自動で起動します。

環境変数

変数	説明	デフォルト
`EXPRESS_SERVER_URL`	キャンバスサーバーの URL	`http://127.0.0.1:3000`
`ENABLE_CANVAS_SYNC`	キャンバスのリアルタイム同期を有効化	`true`
`EXCALIDRAW_NO_AUTOSTART`	`1` に設定するとキャンバスの自動起動を無効化	（未設定）
`EXCALIDRAW_EXPORT_DIR`	MCP のファイルエクスポート先に指定できるベースディレクトリ	現在の作業ディレクトリ
`EXCALIDRAW_RENDER_MAX_DIM`	ヘッドレス PNG の最大辺（ピクセル）	`8192`
`EXCALIDRAW_DATA_DIR`	任意のローカル永続状態ディレクトリ	（未設定。メモリー内）
`EXCALIDRAW_SHARE_UPLOAD_URL`	`share` が暗号化されたシーンをアップロードする URL（excalidraw-json の `POST` エンドポイント）	`https://json.excalidraw.com/api/v2/post/`
`EXCALIDRAW_SHARE_BASE_URL`	共有リンクを開く Excalidraw アプリ	`https://excalidraw.com`
`PORT` / `HOST`	キャンバスサーバーのバインドアドレス	`3000` / `127.0.0.1`
`LOG_LEVEL`	ログの詳細度（`error`、`warn`、`info`、`debug`）	`info`
`LOG_FILE_PATH`	ログファイルの保存場所	`~/Library/Logs/excalidraw-mcp.log`（macOS）、`$XDG_STATE_HOME/excalidraw-mcp/excalidraw.log`（Linux）、`%LOCALAPPDATA%\Excalidraw-MCP\excalidraw.log`（Windows）

永続的なキャンバス状態

EXCALIDRAW_DATA_DIR を設定すると、キャンバスサーバーの再起動後に要素、サーバーが認識している画像ファイル、および名前付きスナップショットを復元できます。npm run build の後、ソースチェックアウトから以下を実行します。

EXCALIDRAW_DATA_DIR=/absolute/private/canvas-data \
  node dist/bin.js start

この変数が未設定の場合、動作と API のセマンティクスはメモリ内のままであり、永続状態ディレクトリは作成されません。有効にすると、ディレクトリにはバージョン管理された canvas-state-v1.json チェックポイント、blobs/ ディレクトリ、および実行時の canvas-state.lock/ 所有権ディレクトリが含まれます。画像ペイロードは、各ファイル ID のパス安全な SHA-256 に基づく不変のファイル ID ブロブとして一度だけ保存されます。チェックポイントは別個のコンテンツ SHA-256 を記録し、参照のみを含みます。新しいブロブは、チェックポイントがそれを参照できるようになる前に、フラッシュされアトミックに公開されます。受け入れられた各変更は、一時チェックポイントをフラッシュし、サーバーがその変更をブロードキャストまたは確認応答する前にアトミックに名前を変更します。シリアライゼーションはオブジェクトキーを再帰的にソートし、シーンのスタッキング順序を保持し、ファイルおよび名前付きスナップショットのメタデータを安定した ID/名前順で保存します。無効な JSON、サポートされていないスキーマ、非正規のチェックポイントパス、欠落したブロブ、およびブロブの整合性エラーは、復元可能な状態を空のシーンに置き換えるのではなく、起動を停止させます。

永続モードでは 2 つの REST ルールがより厳格になり、どちらも 409 を返します。要素が参照する前に画像のファイル (POST /api/files) をアップロードすること、および異なるコンテンツでファイル ID を再アップロードしないことです。キャンバスタブと import はすでにこのように動作します。

チェックポイントがすでに所定の場所に名前変更されているにもかかわらず、最終的なディレクトリのフラッシュが失敗した場合、リクエストは成功のブロードキャストなしで失敗し、再起動まで以降の変更は拒否されます。公開されたシーンはメモリ内に留まるため、ディスク上のファイルと一致します。失敗したリクエストは復元されたシーンに現れる可能性があります。Windows では、Node.js はディレクトリの fsync を提供しないため、ストアはファイルの内容をフラッシュし、同じディレクトリの耐久性バリアを主張することなくアトミックな公開を使用します。

データディレクトリのロックは、サーバーが異なるポートを使用している場合も含め、1 つのプロセスにその永続状態の排他的所有権を付与します。これはトークン固有のオーナーファイルを 1 つ保存するため、古いロックの再利用が新しいオーナーの証拠を削除することはできません。既存の pidfile は別の役割を持ちます。それは start / stop ライフサイクルコマンドのためにリッスンしているプロセスを識別します。ローカルファイルシステムと単一のライターがサポートされています。ネットワークファイルシステム、共有マルチライターアクセス、自動ブロブガベージコレクション、データベース、およびクラウド永続化は対象外です。

プライバシー: 永続状態には図と埋め込み画像のペイロードが含まれます。ディレクトリはリポジトリや共有フォルダの外に保ち、そのアクセス許可を制限し、コンテナを使用する場合はプライベートな書き込み可能ボリュームとしてマウントしてください。

Claude Desktop

設定場所:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

npx (推奨)

{
  "mcpServers": {
    "excalidraw": {
      "command": "npx",
      "args": ["-y", "mcp-excalidraw-server"]
    }
  }
}

ローカル (node)

{
  "mcpServers": {
    "excalidraw": {
      "command": "node",
      "args": ["/absolute/path/to/mcp_excalidraw/dist/index.js"],
      "env": {
        "EXPRESS_SERVER_URL": "http://127.0.0.1:3000",
        "ENABLE_CANVAS_SYNC": "true"
      }
    }
  }
}

Docker

{
  "mcpServers": {
    "excalidraw": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "EXPRESS_SERVER_URL=http://host.docker.internal:3000",
        "-e", "ENABLE_CANVAS_SYNC=true",
        "ghcr.io/yctimlin/mcp_excalidraw:latest"
      ]
    }
  }
}

Claude Code

npx (推奨)

claude mcp add excalidraw --scope user -- npx -y mcp-excalidraw-server

ヒント: コーディングエージェントの場合、スキル + CLI は多くの場合 MCP 設定を完全に上回ります。エージェントにスキルルートを選択させてから、npx -y mcp-excalidraw-server install-skill --dir <skills-root> を実行してください。

ローカル (node) - ユーザーレベル (すべてのプロジェクトで利用可能):

claude mcp add excalidraw --scope user \
  -e EXPRESS_SERVER_URL=http://127.0.0.1:3000 \
  -e ENABLE_CANVAS_SYNC=true \
  -- node /absolute/path/to/mcp_excalidraw/dist/index.js

Docker

claude mcp add excalidraw --scope user \
  -- docker run -i --rm \
  -e EXPRESS_SERVER_URL=http://host.docker.internal:3000 \
  -e ENABLE_CANVAS_SYNC=true \
  ghcr.io/yctimlin/mcp_excalidraw:latest

サーバーの管理:

claude mcp list              # List configured servers
claude mcp remove excalidraw # Remove a server

Cursor

設定場所: プロジェクトルートの .cursor/mcp.json (またはグローバル設定の場合は ~/.cursor/mcp.json)

npx (推奨)

{
  "mcpServers": {
    "excalidraw": {
      "command": "npx",
      "args": ["-y", "mcp-excalidraw-server"]
    }
  }
}

Docker

{
  "mcpServers": {
    "excalidraw": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "EXPRESS_SERVER_URL=http://host.docker.internal:3000",
        "-e", "ENABLE_CANVAS_SYNC=true",
        "ghcr.io/yctimlin/mcp_excalidraw:latest"
      ]
    }
  }
}

Codex CLI

npx (推奨)

codex mcp add excalidraw -- npx -y mcp-excalidraw-server

Docker

codex mcp add excalidraw \
  -- docker run -i --rm \
  -e EXPRESS_SERVER_URL=http://host.docker.internal:3000 \
  -e ENABLE_CANVAS_SYNC=true \
  ghcr.io/yctimlin/mcp_excalidraw:latest

サーバーの管理:

codex mcp list              # List configured servers
codex mcp remove excalidraw # Remove a server

OpenCode

設定場所: ~/.config/opencode/opencode.json またはプロジェクトレベルの opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "excalidraw": {
      "type": "local",
      "command": ["npx", "-y", "mcp-excalidraw-server"],
      "enabled": true
    }
  }
}

Antigravity (Google)

設定場所: ~/.gemini/antigravity/mcp_config.json

{
  "mcpServers": {
    "excalidraw": {
      "command": "npx",
      "args": ["-y", "mcp-excalidraw-server"]
    }
  }
}

注意事項

Docker のネットワーク：ホストマシン上で実行中のキャンバスサーバーに接続するには、host.docker.internal を使用してください。Linux では、--add-host=host.docker.internal:host-gateway を指定するか、172.17.0.1 を使用する必要がある場合があります。Docker MCP イメージでは EXCALIDRAW_NO_AUTOSTART=1 が設定されています（フロントエンドのビルドが含まれていないため）。キャンバスは独立したコンテナーとして実行してください。
キャンバスの永続化：デフォルトでは、要素と名前付きスナップショットはメモリ上に保持され、サーバーの再起動時に失われます。要素、サーバーが認識している画像ファイル、名前付きスナップショットを再起動後も復元できるようにするには、EXCALIDRAW_DATA_DIR を設定してください（キャンバス状態の永続化を参照）。単独の .excalidraw ファイルを保存するには export を使用してください。デフォルトのメモリ上での動作では、スナップショットを作成するだけでは再起動後に復元できません。

MCP ツール（合計26個）

カテゴリ	ツール
要素の CRUD	`create_element`、`get_element`、`update_element`、`delete_element`、`query_elements`、`batch_create_elements`、`duplicate_elements`
レイアウト	`align_elements`、`distribute_elements`、`group_elements`、`ungroup_elements`、`lock_elements`、`unlock_elements`
シーンの把握	`describe_scene`、`get_canvas_screenshot`
ファイル I/O	`export_scene`、`import_scene`、`export_to_image`、`export_to_excalidraw_url`、`create_from_mermaid`
状態管理	`clear_canvas`、`snapshot_scene`、`restore_snapshot`
ビューポート	`set_viewport`
デザインガイド	`read_diagram_guide`
リソース	`get_resource`

完全なスキーマは tools/list、または skills/excalidraw-skill/references/cheatsheet.md から確認できます。

ビューポートグループのフォーカスでは、viewportZoomFactor を使って表示範囲を調整できます。

{
  "scrollToElementIds": ["id1", "id2", "id3"],
  "viewportZoomFactor": 0.85
}

scrollToElementIds は指定したすべての要素が収まるようにズームし、scrollToElementId は現在のズームを変えずに1つの要素を中央に配置します。1つのリクエストで指定できるビューポートモードは1つだけです。viewportZoomFactor に指定できる値は、0より大きく1以下です。

クイックスタート（ソースから／Docker）

ソースから実行する場合（Node >= 20）：

npm ci
npm run build
PORT=3000 npm run canvas          # canvas server (terminal 1)
node dist/index.js                # MCP server over stdio (terminal 2, usually launched by your MCP client)
node dist/bin.js status           # or drive the CLI straight from the build

Docker キャンバスサーバー：

docker run -d -p 3000:3000 --name mcp-excalidraw-canvas ghcr.io/yctimlin/mcp_excalidraw-canvas:latest

MCP サーバーのイメージ：ghcr.io/yctimlin/mcp_excalidraw:latest（stdio。EXPRESS_SERVER_URL をキャンバスコンテナーに向けてください）。

テスト

CLI スモークテスト

npx -y mcp-excalidraw-server start
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

キャンバスのスモークテスト（HTTP）

curl http://127.0.0.1:3000/health

リグレッションチェック

npm test はサーバーをビルドし、4つのテストスイートを実行します。各スイートは単独でも実行できます。

npm test
npm run test:mcp      # MCP stdio wire protocol (see below)
npm run test:bind     # default loopback bind, duplicate-start refusal
npm run test:render   # headless renderer, export order keys, scene-prep stability
npm run test:state    # atomic import and snapshot restore, sync validation

キャンバスのブラウザーリグレッションテスト

これらの Chromium テストでは、アプリをビルドし、分離された localhost サーバーを起動します。フレームの再読み込み／再接続、複合シーン、読み込み失敗時の同期保護、古いレスポンス、クリア／削除、Mermaid のインポート、SVG のエクスポート、画像のドロップ、フォント読み込み後のテキスト計測を検証します。既存のサーバーの再利用は拒否されます。ポート51910が使用中の場合は、CANVAS_TEST_PORT を設定してください。

npx playwright install chromium
npm run type-check:frontend
npm run test:canvas

MCP stdio ワイヤーテスト

生の JSON-RPC フレームを使って dist/index.js を実行し、2つのプロトコル世代を検証します。server/discover、ハンドシェイクなしで送信されるツール呼び出し、未対応のプロトコルリビジョンと不正な _meta エンベロープの拒否、従来の initialize 経路を確認します。

npm run test:mcp

MCP スモークテスト（MCP Inspector）

ツールを一覧表示：

npx @modelcontextprotocol/inspector --cli \
  -e EXPRESS_SERVER_URL=http://127.0.0.1:3000 \
  -e ENABLE_CANVAS_SYNC=true -- \
  node dist/index.js --method tools/list

長方形を作成：

npx @modelcontextprotocol/inspector --cli \
  -e EXPRESS_SERVER_URL=http://127.0.0.1:3000 \
  -e ENABLE_CANVAS_SYNC=true -- \
  node dist/index.js --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

フロントエンドのスクリーンショット（agent-browser）

UI のチェックに agent-browser を使用する場合：

agent-browser install
agent-browser open http://127.0.0.1:3000
agent-browser wait --load networkidle
agent-browser screenshot /tmp/canvas.png

FAQ

公式の Excalidraw MCP との違いは何ですか？

公式 Excalidraw MCP はチャットウィジェットです。プロンプトを入力すると、会話に図がストリーミングされます（モデルが利用できるツールは2つです）。このプロジェクトはコーディングエージェント向けのワークベンチです。要素単位での作成／読み取り／更新／削除、レイアウトツール、モデルが参照できるスクリーンショット、スナップショット、.excalidraw ファイルの I/O に対応した永続的なローカルキャンバスを提供し、CLI、MCP、REST 経由で操作できます。詳細な比較表を参照してください。

どの AI ツールで使えますか？

Claude Code、Claude Desktop、Cursor、Codex CLI、OpenCode、Google Antigravity については以下で説明しています。ただし、シェルコマンドを実行できるエージェントなら CLI を、MCP クライアントなら MCP サーバーを利用できます。また、LangChain やカスタムアプリなど、その他のものからは REST API を利用できます。

AI は描画した図を実際に確認できますか？

はい。それがこのツールの中核機能です。describe は構造化されたテキスト要約（ID、位置、ラベル、接続）を返し、screenshot はレンダリング済みの PNG を返します。エージェントは両方を使って、ラベルの途切れ、重なり、矢印の経路の問題を検出し、要素ごとに修正します。

ブラウザーを開いておく必要はありますか？

いいえ。スクリーンショットと PNG／SVG のエクスポートはキャンバスサーバー内でヘッドレスにレンダリングされ（「ヘッドレスレンダリング」を参照）、それ以外の操作（要素の作成、クエリ、更新、.excalidraw ファイルの操作）にもブラウザーは不要です。開いているタブが必要なのは、Mermaid の変換（ブラウザー内でレイアウトを行います）とビューポート制御（カメラを動かします）の 2 つだけです。その場合、CLI はコード 4 で終了し、その旨を通知します。人がエージェントの描画を見守るには、URL を開く方法が引き続き使えます。

図は永続化されますか？

デフォルトでは、キャンバスはメモリ内に保持されます（再起動すると空のキャンバスになります）。EXCALIDRAW_DATA_DIR を設定すると、要素、サーバーが認識している画像ファイル、名前付きスナップショットがローカルに自動保存され、再起動後に復元されます。移植可能でレビュー可能な成果物については、必要に応じて .excalidraw ファイルとしてエクスポートし、リポジトリにコミットしてください。

excalidraw.com の共有リンクは非公開ですか？

share は、アップロード前にシーンをローカルで AES-GCM によって暗号化します。復号キーは URL フラグメントにのみ含まれており、excalidraw.com のサーバーから見えることはありません。リンク全体を渡された人は誰でも図を表示できます。

共有リンクの接続先をセルフホストの Excalidraw にできますか？

はい。EXCALIDRAW_SHARE_UPLOAD_URL にストレージバックエンドのシーンエンドポイントを、EXCALIDRAW_SHARE_BASE_URL に Excalidraw アプリを設定します。たとえば、エンドポイントが <storage>/api/v2/scenes/ となる alswl/excalidraw-storage-backend のように、excalidraw-json API に対応するバックエンドならどれでも動作します。

EXCALIDRAW_SHARE_UPLOAD_URL=https://draw.example.com/api/v2/scenes/ \
EXCALIDRAW_SHARE_BASE_URL=https://draw.example.com \
  npx -y mcp-excalidraw-server share

アプリは、同じバックエンドから #json= リンクを読み込める必要があります（alswl のフォークの場合は VITE_APP_BACKEND_V2_GET_URL）。

API キーやクラウドサービスが必要ですか？

API キーは不要です。描画の主要機能は MIT ライセンスのもとでローカルに実行されます。外部への通信は、キャンバスページが esm.sh CDN から Excalidraw のフォントを読み込む処理と、任意の share による excalidraw.com（または上記の独自インスタンス）へのアップロードに限られます。CLI、MCP サーバー、ヘッドレスレンダラーは、それ以外のネットワーク通信を行いません。

MCP を設定せずに使えますか？

はい。コーディングエージェントにはこちらを推奨します。npx -y mcp-excalidraw-server install-skill --dir <skills-root> を実行すると、エージェントはすべての操作を CLI 経由で行います。MCP の設定が必要なのは、Claude Desktop のようなチャットクライアントだけです。

トラブルシューティング

CLI の終了コード 3（キャンバスに接続できません）：status などの状態確認コマンドを実行しているのにサーバーが起動していない、自動起動が無効になっている（EXCALIDRAW_NO_AUTOSTART=1）、または EXPRESS_SERVER_URL がループバック以外のホストを指しています。明示的に start を実行するか、環境変数を修正してください。
CLI の終了コード 4（ブラウザーが必要です）：開いているタブが必要なのは mermaid と screenshot --renderer browser のみです。ブラウザーで http://127.0.0.1:3000 を開いて再試行するか、--renderer browser を外してヘッドレスでレンダリングしてください。
ヘッドレス PNG で CJK／絵文字の代わりに四角が表示されます：同梱フォントはラテン文字をカバーしています。それ以外の文字体系については、resvg がマシンのフォントにフォールバックします（警告が出力されます）。キャンバスサーバーを実行しているマシンに CJK フォントをインストールしてください。
キャンバスが更新されません：EXPRESS_SERVER_URL が実行中のキャンバスサーバーを指していることを確認してください（status に使用中の URL が表示されます）。
オフラインでキャンバスページのフォントが標準的なものになります：ページは Excalidraw の手描き風フォントを esm.sh CDN から読み込むため、インターネットに接続できない場合はシステムフォントにフォールバックします。ヘッドレスのスクリーンショットと render は同梱フォントを使用するため、影響を受けません。
ほかにも問題がある場合：詳細はサーバーログに記録されています。ログの場所は環境変数（LOG_FILE_PATH）に記載されています。

既知の問題／TODO

任意の永続ストレージ：EXCALIDRAW_DATA_DIR を設定すると、ローカルでの再起動時にアトミックに復元できます。デフォルトは引き続きメモリ内ストレージです。
Mermaid 変換にはブラウザーが必要です：mermaid／create_from_mermaid はフロントエンドで図をレイアウトします。v2.1 以降、画像のエクスポートとスクリーンショットはヘッドレスで実行できます。
キャンバスページのフォントは CDN から読み込まれます：キャンバスサーバーから配信すれば、ページを完全にオフラインで利用できるようになります。

コントリビューションを歓迎します！

開発

npm run type-check
npm run build
npm run cli -- status      # run the CLI from the local build
npm run sync:skills        # after editing skills/excalidraw-skill, sync the repo-local agent copy

バグ報告とプルリクエストは GitHub の Issues で歓迎しています。このプロジェクトが役に立ったら、⭐ を付けていただけると、ほかの人にも見つけてもらいやすくなります。

ライセンス

リンク： npm パッケージ · GitHub · Issues · デモ動画

今後の展開に興味がある方は、X でフォローしてください： @ycalintim。

Markdown 対応

ログインしてコメント

MCP は初めてですか？

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

入門ガイドを読む

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。

mcp-excalidraw

mcp-excalidraw について

主な機能

活用シーン

MCP 対応

設定

ツール

詳細

Excalidraw MCP サーバー、CLI、エージェントスキル

デモ

目次

概要

公式 Excalidraw MCP との違い

新着情報

v2.1.2 — 修正

v2.1.1 — 修正

v2.1 — ヘッドレスレンダリング

v2.0 — 相互運用性に優れたエクスポートと MCP 2026-07-28

v1.1 — CLI ファースト

インストール

最も簡単な方法：エージェントにインストールさせる

手動インストール

60 秒で始めるクイックスタート（CLI）

エージェントスキル

CLI リファレンス

ヘッドレスレンダリング

MCP クライアントの設定

環境変数

永続的なキャンバス状態

Claude Desktop

Claude Code

Cursor

Codex CLI

OpenCode

Antigravity (Google)

注意事項

MCP ツール（合計26個）

クイックスタート（ソースから／Docker）

テスト

CLI スモークテスト

キャンバスのスモークテスト（HTTP）

リグレッションチェック

キャンバスのブラウザーリグレッションテスト

MCP stdio ワイヤーテスト

MCP スモークテスト（MCP Inspector）

フロントエンドのスクリーンショット（agent-browser）

FAQ

公式の Excalidraw MCP との違いは何ですか？

どの AI ツールで使えますか？

AI は描画した図を実際に確認できますか？

ブラウザーを開いておく必要はありますか？

図は永続化されますか？

excalidraw.com の共有リンクは非公開ですか？

共有リンクの接続先をセルフホストの Excalidraw にできますか？

API キーやクラウドサービスが必要ですか？

MCP を設定せずに使えますか？

トラブルシューティング

既知の問題／TODO

開発

ライセンス

コメント

MCP は初めてですか？

MCP（Model Context Protocol）とは？

MCP サーバーとクライアントの違いは？

ローカルとリモート、どちらを選ぶべき？

Claude や Cursor にサーバーを導入するには？

掲載プロジェクトは審査されていますか？「認証済み」とは？

自分のプロジェクトが掲載されています。どう申請できますか？