excalidraw

excalidraw-mcp-server

セキュリティ強化、インライン図のレンダリング、リアルタイムキャンバス同期に対応した、唯一の Excalidraw MCP サーバーです。

できること

AI に図の描画を頼むと、チャット内にそのまま表示されます。この MCP サーバーは、API 認証、レート制限、すべての操作に対する入力検証を備えた、Excalidraw 形式の描画ツール一式を Claude Desktop、ChatGPT、VS Code、Cursor に提供します。

v2.0 ではMCP Apps に対応しました。図はインタラクティブな SVG ウィジェットとしてインラインでストリーミング表示され、描画アニメーションも利用できます。また、ワンクリックで図を excalidraw.com にエクスポートできます。

2 つのモード、設定不要

スタンドアロンモード（デフォルト）――インストールするだけですぐに使えます。サーバーはインプロセスの要素ストアで動作します。キャンバスサーバー、API キー、セットアップは不要です。MCP クライアントがツールを呼び出すと、図がインラインでレンダリングされます。

接続モード――オプションのキャンバスサーバーを起動すると、ブラウザーとリアルタイムで同期できます。複数のクライアントが、認証済みの WebSocket 接続を通じて同じキャンバス上で共同作業できます。ファイルへの永続化により、再起動後も状態が保持されます。

サーバーは使用するモードを自動検出します。キャンバスサーバーに接続できる場合は接続し、そうでない場合はスタンドアロンモードにフォールバックします。

アーキテクチャ

excalidraw-mcp-server で作成した図です――Excalidraw で編集

機能

MCP Apps（v2.0）

• Claude Desktop、ChatGPT、VS Code でのインライン図レンダリング
• 要素の到着に合わせて描画アニメーションを表示する SVG ストリーミング
• ワンクリックで excalidraw.com にエクスポート
• read_me ツールによる要素リファレンスチートシート

16 個の MCP ツール

• 要素の作成、更新、削除、検索（長方形、楕円、ひし形、矢印、テキスト、線、フリードロー）
• 一度に最大 100 個の要素を一括作成
• グループ化、グループ解除、整列、分布、ロック、ロック解除
• Mermaid 図への変換
• SVG と PNG へのエクスポート

セキュリティ

• 定時間比較による API キー認証
• オリジン制限付き CORS（ワイルドカードなし）
• トークンとオリジンの検証による WebSocket 認証
• 標準および厳格なレート制限ティア
• .strict() をすべてのエンドポイントに適用した、上限付き Zod スキーマ
• CSP を含む Helmet.js セキュリティヘッダー

インフラストラクチャ

• ブラウザークライアント間のリアルタイム WebSocket 同期
• オプションのアトミック書き込みによるファイル永続化
• 構造化された pino 監査ログ

インストール

npm install -g excalidraw-mcp-server

または、直接実行します。

npx excalidraw-mcp-server

クイックスタート

スタンドアロン（ほとんどのユーザーにおすすめ）

MCP クライアントでサーバーを指定するだけです。キャンバスサーバーは不要です。

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

続いて、AI に次のように頼みます。「ロードバランサー、3 台のアプリサーバー、データベースを示すアーキテクチャ図を描いて」

接続モード（ブラウザーとのリアルタイム同期）

# Generate an API key
node scripts/generate-api-key.cjs

# Start the canvas server
EXCALIDRAW_API_KEY=<your-key> npm run canvas

# Open http://localhost:3000 to see the live canvas

同じ API キーを使って、MCP クライアントでサーバーを指定します。

{
  "mcpServers": {
    "excalidraw": {
      "command": "npx",
      "args": ["excalidraw-mcp-server"],
      "env": {
        "EXCALIDRAW_API_KEY": "<your-key>",
        "CANVAS_SERVER_URL": "http://127.0.0.1:3000"
      }
    }
  }
}

MCP ツール

ツール	説明
create_view	ストリーミングアニメーション付きのインライン SVG ウィジェットとして要素を描画します（MCP Apps）
read_me	要素のリファレンス早見表（種類、色、サイズ設定のヒント）を取得します
create_element	単一の要素（長方形、楕円、ひし形、矢印、テキスト、線、フリーハンド描画）を作成します
update_element	ID を指定して既存の要素を更新します
delete_element	ID を指定して要素を削除します
query_elements	種類、ロック状態、またはグループ ID で要素を検索します
get_resource	シーンの状態、すべての要素、テーマ、またはライブラリを取得します
batch_create_elements	1 回の呼び出しで最大 100 個の要素を作成します
group_elements	複数の要素をグループ化します
ungroup_elements	要素をグループから解除します
align_elements	要素を整列します（左、中央、右、上、中央、下）
distribute_elements	要素を均等に配置します（水平または垂直）
lock_elements	要素をロックして変更を防止します
unlock_elements	要素のロックを解除します
create_from_mermaid	Mermaid ダイアグラムを Excalidraw の要素に変換します
export_scene	キャンバスを SVG または PNG としてエクスポートします

セキュリティ比較

機能	一般的な MCP サーバー	excalidraw-mcp-server
認証	なし	API キー（一定時間比較）
CORS	* ワイルドカード	オリジン許可リスト
WebSocket 認証	なし	トークン + オリジン検証
レート制限	なし	標準 + 厳格なティア
入力検証	最小限	.strict() を使用した制約付き Zod
セキュリティヘッダー	なし	Helmet.js + CSP
リクエストサイズ制限	なし	本文 512KB、WebSocket 1MB
監査ログ	なし	構造化された pino ログ

設定

すべての設定は環境変数で行います。.env.example を .env にコピーし、必要に応じて調整してください。

変数	デフォルト	説明
STANDALONE_MODE	true	プロセス内ストアを使用します（キャンバスサーバーは不要）
CANVAS_HOST	127.0.0.1	キャンバスサーバーのバインドアドレス
CANVAS_PORT	3000	キャンバスサーバーのポート
EXCALIDRAW_API_KEY	自動生成	認証用 API キー（32 文字以上）
CORS_ALLOWED_ORIGINS	http://localhost:3000,http://127.0.0.1:3000	カンマ区切りのオリジン許可リスト
RATE_LIMIT_WINDOW_MS	60000	ミリ秒単位のレート制限ウィンドウ
RATE_LIMIT_MAX_REQUESTS	100	ウィンドウあたりの最大リクエスト数（標準ティア）
PERSISTENCE_ENABLED	false	ファイルベースの永続化を有効にします
PERSISTENCE_DIR	./data	永続ストレージのディレクトリ
CANVAS_SERVER_URL	http://127.0.0.1:3000	MCP サーバーがキャンバスに接続する際に使用する URL
LOG_LEVEL	info	ログレベル：debug、info、warn、error
AUDIT_LOG_ENABLED	true	監査ログを有効にします
MAX_ELEMENTS	10000	キャンバス上の要素の最大数
MAX_BATCH_SIZE	100	一括作成あたりの要素の最大数

MCP クライアントの設定

Claude Desktop

claude_desktop_config.json に追加します：

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

Cursor

プロジェクトのルートにある .cursor/mcp.json に追加します：

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

VS Code

MCP 設定に追加します：

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

接続モードでは、上記の設定に "env": { "EXCALIDRAW_API_KEY": "<key>", "CANVAS_SERVER_URL": "http://127.0.0.1:3000" } を追加します。<key> を node scripts/generate-api-key.cjs で生成したキーに置き換えてください。

開発

# Install dependencies
npm ci

# Run in development mode (watch + Vite dev server)
npm run dev

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint
npm run lint

# Type check
npm run type-check

# Build (server + widget + frontend)
npm run build

プロジェクト構成

src/
  mcp/              MCP server (stdio transport)
    tools/          16 tool implementations
    apps/           MCP Apps wiring, standalone store, cheatsheet
    schemas/        Zod schemas and input limits
    canvas-client.ts  HTTP client for canvas server
    index.ts        MCP server entry point
  canvas/           Canvas server (Express + WebSocket)
    middleware/      Auth, CORS, rate limiting, audit, security headers
    routes/         REST API routes + SVG export
    ws/             WebSocket handler and protocol
    store/          Element storage (memory + file)
    index.ts        Canvas server entry point
  shared/           Shared config, types, logging
widget/             MCP Apps inline widget (Vite + singlefile build)
frontend/           Excalidraw React frontend (browser)
test/               Unit and integration tests (290 tests)

v1.x からの移行

設定不要でアップグレードできます。元の 14 個のツールはすべて同じように動作し、create_view と read_me が追加されています。キャンバスサーバーは任意になりました（スタンドアロンモードが自動的に有効になります）。

npm install -g excalidraw-mcp-server@2

既存の MCP クライアント設定（stdio トランスポート、ツール名）は、変更せずに引き続き使用できます。

ライセンス

MIT