Excalidraw MCPの導入と使い方｜Claude Code・Cursor・Codex設定と実装の選び方

Excalidraw MCPは、Model Context Protocol（MCP）を介してAIエージェントからExcalidrawのキャンバスを操作する仕組みです。ただし「Excalidraw MCP」と呼ばれるものは1つではなく、Excalidraw公式のワンショット描画ウィジェットと、コーディングエージェント向けに26ツールとCLIを備えたコミュニティ版 mcp-excalidraw-server が別物として存在します。選ぶ実装を間違えると、要素単位の修正もファイル書き出しもできません。ここでは3系統の違い、Claude Code・Claude Desktop・Cursor・Codex CLIでの設定、そして2026年7月6日公開の v1.1.0 で導入手順が大きく変わった点を、公式リポジトリとnpmの実データに基づいて整理します。

まとめ

• 実装は3系統。公式 excalidraw/excalidraw-mcp（ホスト版 mcp.excalidraw.com）はチャット内にワンショットで図を流し込むウィジェット。コミュニティ版 mcp-excalidraw-server（yctimlin）は26ツール＋CLI＋Agent Skillを持つ作業台。Excalidraw+ MCPはExcalidraw Plusワークスペース連携で公開ベータ。
• コーディングエージェント（Claude Code / Codex CLI / Cursor）ならコミュニティ版。AIが自分の描いた図をスクリーンショットで確認して直せるのはこちらだけで、.excalidraw ファイルをリポジトリにコミットできる。
• v1.1.0（npm 2026-07-06）でCLI-Firstに刷新。リポジトリのcloneも npm run build も不要になり、描画コマンドがキャンバスサーバーを自動起動する。旧来の「2ターミナル同時起動」「絶対パス指定」は必須ではなくなった。
• 設定は全クライアント共通で npx -y mcp-excalidraw-server の1行。Claude Codeなら claude mcp add excalidraw --scope user -- npx -y mcp-excalidraw-server。
• キャンバスはインメモリ。サーバーを再起動すると図は消える。export で .excalidraw を書き出す運用が前提。

Excalidraw MCPの3つの実装と、用途別の選定基準

検索で「Excalidraw MCP」を追うと、名前の似た別プロジェクトが混ざって出てきます。最初に切り分けておきます。

公式 Excalidraw MCP（mcp.excalidraw.com）はチャット内ワンショット描画

Excalidraw組織が公開する excalidraw/excalidraw-mcp は、プロンプトから手描き風の図をチャット内へストリーミング表示し、フルスクリーンで編集できるMCPアプリです。ホスト版が https://mcp.excalidraw.com で提供され、MCP Appsに対応するクライアント（Claude、ChatGPT、VS Code、Goose ほか）から接続できます。リリースは v0.3.2（2026年2月9日）です。

コミュニティ版の比較表によれば、公式版がモデルに渡すツールはフォーマット参照と create_view の2つで、要素の更新は削除マーカーを含めたシーン全体の宣言的な再送で行う方式とされています。つまりモデル側から要素を1つずつ直したりファイルへ書き出したりする経路は持ちません。「Claudeとの会話の流れで図を1枚見たい」用途にはこれで十分です。

コミュニティ版 mcp-excalidraw-server は26ツールを持つ作業台

yctimlin氏の mcp_excalidraw（npmパッケージ名 mcp-excalidraw-server、MITライセンス、GitHubスター2,153＝2026年7月時点）は、ローカルに常駐するキャンバスサーバーへエージェントが描画・照会・修正を繰り返す構成です。最新版は 1.1.0（npm公開日2026年7月6日／前版1.0.7は2026年5月1日）。前提条件はNode.js 18以上だけで、APIキーは不要です。

この記事で「Excalidraw MCP連携」として扱う実務的な対象は、基本的にこちらです。GitHubのリリースタグは付与されていないため、バージョン確認はnpm（npm view mcp-excalidraw-server version）で行うのが確実です。

Excalidraw+ MCPはPlusワークスペース連携（公開ベータ）

Excalidraw+の利用者向けには、ワークスペースへAIクライアントからアクセスするExcalidraw+ MCPが公開ベータで提供されています。エンドポイントは https://api.excalidraw.com/api/v1/mcp、streamable HTTPトランスポートとベアラートークン認証で、利用にはExcalidraw Plusアカウントで発行したAPIキーが必要です。公式ドキュメントはベータ期間中にツール名・スキーマ・出力フォーマットが変わりうると明記しており、本番の業務フローに組み込むのは時期尚早です。

判断はこうです。コードベースを読ませてアーキテクチャ図を作らせ、リポジトリに図を置きたいならコミュニティ版一択。チャットで図を1枚見せたいだけなら公式版で、導入コストはゼロです。Excalidraw+を既に契約していてクラウド側の図を触りたい場合のみ、Excalidraw+ MCPをベータと承知で試す価値があります。

紛らわしい別パッケージ excalidraw-mcp-server との取り違えに注意

npmには excalidraw-mcp-server という語順の逆さまなパッケージも存在し、こちらは別作者（debu-sinha氏）の「APIキー認証とレート制限を備えたセキュリティ強化版」で、最新は 2.0.0（2026年2月8日公開）です。本記事が扱う mcp-excalidraw-server（yctimlin氏）と混同すると、記事どおりのコマンドが動きません。「Excalidraw MCPのv2.0」といった情報を見かけたら、まずどちらのパッケージの話かを確認してください。yctimlin氏の mcp-excalidraw-server に v2系は存在せず、最新は 1.1.0 です。

v1.1.0のCLI-Firstで変わった導入手順（clone不要・キャンバス自動起動）

ここが2026年7月時点で最も情報が古くなりやすい箇所です。v1.1以前は「リポジトリをclone → npm ci → npm run build → キャンバスサーバーとMCPサーバーを2つのターミナルで起動」という手順が必要でしたが、v1.1でCLIが第一級になり、描画系コマンドとMCPサーバーがキャンバスサーバーを自動起動するようになりました（自動起動を止めるには EXCALIDRAW_NO_AUTOSTART=1）。cloneもビルドも、コントリビューター以外には不要です。

npxだけで動かす60秒クイックスタート

# キャンバスを起動（描画コマンドが自動起動もする）
npx -y mcp-excalidraw-server start
# ブラウザで開く（macOS。LinuxはxdgOpen、Windowsはstart）
# スクリーンショットとMermaid変換にはタブが開いている必要がある
open http://127.0.0.1:3000

# 要素を作る（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

# エージェントに自分の絵を見せる
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

v1.1で追加された apply は、作成・更新・削除を1回の呼び出しにまとめられます。図の一括修正をエージェントに任せるときは、コマンドを何度も往復させるより確実です。

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:3000 です。HOST=0.0.0.0 でネットワークに露出させる場合、このAPIには認証機構が無いため、前段でネットワーク側のアクセス制御が必須になります。社内共有したいという理由で安易に 0.0.0.0 にしないでください。

Agent Skillはinstall-skillコマンドで配置する

Claude CodeやCodex CLIのようなコーディングエージェントでは、MCP設定よりもAgent Skillの導入が推奨経路になりました。スキルはレイアウト計画、スクリーンショットで検証して直す品質ループ、矢印のルーティング、アンチパターン、ファイル入出力までをエージェントに教えます。

# スキルルートを指定して配置（再実行で上書き更新）
npx -y mcp-excalidraw-server install-skill --dir <skills-root>

# 後方互換のショートカット
npx -y mcp-excalidraw-server install-skill                  # ~/.claude/skills へ
npx -y mcp-excalidraw-server install-skill --target codex   # ~/.codex/skills へ

v1.1でスキル自体がCLI-First化したため、スキルを使うのにcloneしたリポジトリもMCP設定も要りません。スキルの仕組み自体についてはClaude Skillsとは何か: AIエージェントに専門スキルを追加する最新拡張機能の概要と目的、Codex側の配置規則はCodex Skillsとは？できること・SKILL.mdの作り方と配置場所を解説【2026年最新】が対応します。

Claude Desktop・Claude Code・Cursor・Codex CLIの設定差分

MCPサーバーとして使う場合、v1.1以降はどのクライアントでも npx -y mcp-excalidraw-server を起動コマンドにするのが最短です。絶対パスも環境変数も、既定値のままなら不要になりました。

設定ファイルの場所とnpx設定の共通形

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
    }
  }
}

CLI系はコマンド1行です。Claude Codeの --scope user は全プロジェクトで使える個人設定、--scope project は .mcp.json に書かれチームで共有されます。図をリポジトリ資産として運用するなら project スコープが噛み合います。

# 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

Docker構成とLinuxのhost.docker.internal

Dockerで動かす場合、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

コンテナからホスト側のキャンバスに届かせるには EXPRESS_SERVER_URL=http://host.docker.internal:3000 を渡します。Linuxでは host.docker.internal が既定で解決されないため、--add-host=host.docker.internal:host-gateway を付けるか 172.17.0.1 を直接指定します。macOS向けの設定をそのままLinuxに持ち込むと接続不能になるのは、ほぼこれが原因です。

26ツールの分類と、AIが自分の図を見て直す閉ループ

コミュニティ版がMCPクライアントへ公開するツールは26個です。用途別に整理すると次のようになります。

実務で効くのはシーン認識の2つです。describe_scene がID・座標・ラベル・接続関係を構造化テキストで返し、get_canvas_screenshot が描画結果のPNGを返すため、エージェントは「描く→見る→直す」を要素単位で回せます。ラベルがボックスからはみ出した、矢印が図形を横切った、といった破綻をモデル自身が検出して修正できるのは、ワンショット生成との決定的な差です。

永続化は export_scene で .excalidraw をリポジトリに書き出し、変更時に import_scene で読み戻して再編集する流れになります。作業中の一時退避には snapshot_scene / restore_snapshot を使います。

なお、キャンバスサーバーはMCPを介さずHTTPで直接叩けるREST APIも公開しています。MCPクライアントもCLIも使わないフレームワーク（LangChainや自作アプリ）からは、このREST APIが3つ目の経路になります。

Mermaidと比べてExcalidraw MCPを選ぶべきでない場面

Excalidraw MCPを勧めない条件をはっきりさせておきます。図をテキストとしてGitで差分レビューしたいなら、Excalidraw MCPは向いていません。.excalidraw はJSONで座標やスタイルを保持するため、行単位の差分が意味を持ちません。「どのノードが増えたか」をプルリクエストのレビューで読ませたい用途は、Mermaidのテキスト定義が明確に優位です。Mermaid記法の使い方を完全ガイド｜無料のLive Editorでフローチャート・シーケンス図を作成やVSCodeでMermaidを使う方法｜記法・図作成・画像出力とAI拡張mermAIdで扱っている運用が、そのまま代替になります。

生成トークンの効率でもMermaidが有利です。数行のテキストで済む図に対し、Excalidraw MCPは要素ごとの座標・サイズ・接続を指定します。単純なフローチャートを大量に量産する場面で、後者を選ぶ理由はありません。

逆にExcalidraw MCPを選ぶのは、レイアウトの見栄えが成果物の価値に直結する場面です。設計レビューや提案資料に載せるアーキテクチャ概要図のように、余白・配置・強調を人が調整したくなる図は、テキスト定義から自動レイアウトさせるより、AIに描かせて要素単位で直すほうが速く着地します。手描き風のUIも、確定した仕様ではなく議論中の設計であることを視覚的に伝えます。両方を使うなら、テキストで確定できる図はMermaid（create_from_mermaid でキャンバスへ取り込めます）、人が調整する図はExcalidraw、という線引きが実務的です。

頻出エラーと復旧手順

CLIは終了コードで原因を切り分けられます。0 正常、1 エラー、2 使い方の誤り、3 キャンバスに到達不能、4 ブラウザタブが必要、です。

• 終了コード3（キャンバス到達不能）：status のような照会系コマンドは自動起動しません。自動起動を EXCALIDRAW_NO_AUTOSTART=1 で無効化しているか、EXPRESS_SERVER_URL がループバック以外を指しているのも原因です。start を明示実行するか環境変数を直します。
• 終了コード4（ブラウザ必須）：スクリーンショット、画像エクスポート、ビューポート操作、Mermaid変換はフロントエンドで描画するため、http://127.0.0.1:3000 をブラウザで開いた状態が必要です。要素の作成・更新・照会と .excalidraw のJSON書き出しはヘッドレスで動きます。
• キャンバスが更新されない：status が表示するURLと、実際に動いているキャンバスサーバーのURLが一致しているか確認します。
• 再起動したら図が消えた：キャンバスは設計上インメモリで、サーバーを再起動すると白紙に戻ります。仕様であり不具合ではありません。export とスナップショットで退避してください。永続ストレージは未実装のTODOとして公開されています。
• バッチ生成後にupdate/deleteが失敗する：バッチ作成時に要素IDが保持されない不具合で、PR #34（2026年1月24日マージ）で修正済みです。この修正を含むビルド（1.0.6以降）を使っていれば再現しません。

接続そのものを確認するなら、キャンバスのヘルスチェックとCLIのスモークテストの2段階が確実です。

curl http://127.0.0.1:3000/health

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

よくある質問

Excalidraw MCPの利用にAPIキーやアカウントは必要ですか

コミュニティ版 mcp-excalidraw-server は不要です。描画処理はすべてローカル（Node.js 18以上、MITライセンス）で完結し、外部への通信は任意の share コマンドによるexcalidraw.comへのアップロードだけです。一方、Excalidraw+ MCPはExcalidraw Plusアカウントで発行したAPIキーが必須です。

Claude Codeで使うにはMCP設定とSkillのどちらが良いですか

v1.1以降はSkill＋CLIが推奨経路です。npx -y mcp-excalidraw-server install-skill --dir <skills-root> でスキルを入れれば、MCP設定なしでエージェントがCLI経由で描画・確認・書き出しまで行えます。MCP設定が必要なのは、シェルを実行できないチャットクライアント（Claude Desktopなど）です。

share で作った共有リンクは他人に見られませんか

share はアップロード前にシーンをAES-GCMでローカル暗号化し、復号鍵はURLのフラグメント部分にのみ含まれます。フラグメントはexcalidraw.comのサーバーへ送信されません。ただし完全なリンクを渡した相手は誰でも図を閲覧できるため、リンクの配布範囲がそのまま公開範囲になります。

公式版とコミュニティ版を両方入れても大丈夫ですか

接続先が別（公式はリモートのMCPアプリ、コミュニティ版はローカルのstdioサーバー）なので併存できます。ただしMCPサーバーの登録名が衝突しないよう分けてください。常用しないほうを無効化しておくと、モデルに提示されるツール一覧が短く保てます。

バージョンはどこで確認できますか

コミュニティ版はGitHubにリリースタグが無いため、npm view mcp-excalidraw-server version が確実です（2026年7月時点で 1.1.0、公開日2026年7月6日）。公式版はGitHubのリリースページで確認でき、最新は v0.3.2（2026年2月9日）です。パッケージ名が似た excalidraw-mcp-server（v2.0.0）は別作者の別プロジェクトなので、バージョンを比べる前に名前を確認してください。

関連記事

• Claude Skillsとは何か: AIエージェントに専門スキルを追加する最新拡張機能の概要と目的
• Codex Skillsとは？できること・SKILL.mdの作り方と配置場所を解説【2026年最新】
• VSCodeでMermaidを使う方法｜記法・図作成・画像出力とAI拡張mermAId
• Mermaid記法の使い方を完全ガイド｜無料のLive Editorでフローチャート・シーケンス図を作成