Excalidraw Architect Mcp

Excalidraw Architect MCP

エンジニアリングドキュメントに必要なあらゆる図を、AI が手描き風の Excalidraw として生成します。

25 種類の図に対応しています。アーキテクチャ図やフローチャートだけでなく、シーケンス図、状態遷移図、ER モデル、スイムレーン図、タイムライン、ガントチャート、象限図、ファネル図、手描き風の棒グラフ・折れ線グラフ・散布図も作成できます。座標の幻覚も、Figma も、古い PNG も不要です。

課題

コードベースのオンボーディング、新しいシステムの設計、仕組みのドキュメント化において、図なら何ページもの文章で伝えきれないことを数秒で伝えられます。しかし、選択肢には難点があります。

Mermaid はすばやく生成できますが、自由度が低く、ノードのドラッグや視覚的なグループ化、後からの注釈追加ができません。Figma では、図を 1 枚作るのに手作業で 30 分かかります。LLM が Excalidraw の JSON を直接書く場合は座標を幻覚し、ボックスが重なり、矢印が絡み合うため、手作業で修正することになります。

さらに、多くのツールは、得意な図の種類が 1 つだけです。ドキュメントにシーケンス図とアーキテクチャ図の両方が必要になった途端、別のツールに切り替えることになり、見た目もまったく揃いません。

解決策

excalidraw-architect-mcp は「何を」と「どこに」を切り分けます。AI が構造を記述し、エンジンがピクセル単位の計算を行います。

LLM はコンポーネント、アクター、階層、データポイントを指定します。MCP は図の種類に合ったレイアウトアルゴリズムを選び、スタイルを設定して、開いて編集を続けられる本物の .excalidraw ファイルを書き出します。50 以上のテクノロジー（Kafka、PostgreSQL、Redis など）は自動でスタイルが適用され、あらゆる図を自然言語で修正できます。また、Cursor／Claude Code／Windsurf で完全にオフラインで動作し、API キーは不要です。

• 25 種類の図を 1 つの文法で作成 — アーキテクチャ図からガントチャート、散布図まで、すべてを見る
• 本物の手描き風の出力 — roughjs のストローク生成処理を純粋な Python に移植しているため、書き出した SVG／PNG は、整った幾何学形状の近似ではなく Excalidraw のキャンバスと同じ見た目になります
• 毎回完璧なレイアウト — グラフには適応的な間隔調整を備えた Sugiyama を使用し、それ以外には専用のジオメトリーを使用します
• アーキテクチャを考慮したスタイル設定 — 「Kafka」と指定すると、汎用的な長方形ではなく、ストリーム向けのスタイルが適用されたノードになります
• 図と対話 — 自然言語で図の追加、削除、接続の変更ができます。仕様はファイル内に保存されます
• SVG と PNG にエクスポート — ブラウザーも Node.js も不要です
• 変化し続けるアーキテクチャナレッジグラフ — システムをバージョン管理可能なモデルとして任意で保存し、AI によるクエリやリントに利用できます（詳細）

📐 25 種類の図

以下の画像はすべて、この MCP が生成した実際の .excalidraw ファイルで、手動での配置は一切ありません。いずれかをクリックすると、拡大表示できます。

アーキテクチャ コンポーネントと接続	DP 統合 ソース → コア → コンシューマー	シーケンス 時間経過に伴うメッセージ
タイムライン 軸上のイベント	ガントチャート タスクとフェーズ	象限図 2 軸による位置付け
ピラミッド／ファネル ランク別の階層または離脱	ベン図 集合の重なり	ループ ハブを中心に回るフライホイール
棒グラフ カテゴリ別の比較	折れ線グラフ 時間経過に伴う傾向	散布図 分布と相関
入れ子 包含関係による階層	レイヤースタック 抽象化レイヤーの積み重ね	メダリオン データ品質の階層
ER／データモデル エンティティとフィールド	概要図 境界内のスタック	IT の現状 レガシー環境
スイムレーン 部門横断のフロー	プロセス 複数のアクターによるワークフロー	データフロー 役割ごとに範囲を定めたパイプライン
フローチャート 分岐を含む意思決定ロジック	ツリー 親 → 子	組織図 責任範囲とエスカレーション
状態遷移図 状態と遷移

### 選び方と呼び出し方

上のギャラリーは、各タイプを使う頻度が高い順に並んでいます。内部的には5つのファミリーに分類され、それによってレイアウトエンジンが決まります。

ファミリー	タイプ
グラフ	architecture · flowchart
構造	tree · org_chart · state · nested · layers · medallion · er · high_level · it_state
フロー	swimlane · process · data_flow · dp_integration · sequence
幾何	timeline · quadrant · pyramid（＋ funnel） · venn · loop · gantt
チャート	bar · line · scatter

architecture と flowchart はグラフで、nodes と connections を受け取ります。それ以外のタイプはすべて、diagram_type と、そのタイプに合わせた形式の spec を受け取ります。

create_diagram(
    output_path="./checkout.excalidraw",
    diagram_type="sequence",
    spec={
        "title": "Checkout authorization",
        "actors": [{"id": "web", "label": "Web app"}, {"id": "psp", "label": "Payment PSP"}],
        "messages": [
            {"from_id": "web", "to_id": "psp", "label": "authorize"},
            {"from_id": "psp", "to_id": "web", "label": "approved",
             "kind": "return", "focal": True},
        ],
    },
)

各タイプをいつ使うかについては list_diagram_types() を、正確な spec の形式については get_diagram_schema("<type>") を呼び出してください。または、そのまま「PR レビューのフローをスイムレーンで描いて」と依頼できます。

知っておくとよい2つの規約。 要素を1つか2つ "focal": true にするとアクセントカラーが付きます。5つも指定すると、その強調効果が薄れてしまいます。また、クローム（軸、グリッド線、レーンの仕切り）は意図的にくっきりと描画される一方、図形やデータマークは手描き風に描画されます。このコントラストによって、スケッチ風のチャートがノイズっぽくならず、読みやすくなります。

すべてのタイプを編集できます。 検証済みの spec は .excalidraw ファイル内に保存されるため、最初から作り直すのではなく、パッチを適用します。

modify_diagram(path, [{"op": "update_spec", "patch": {"title": "Revised plan"}}])

リストは全体が置き換えられます。1つの階層を変更する場合は、tiers リスト全体を指定してください。

上記の画像をすべて再生成するには、python scripts/generate_showcase.py --png を実行します。

動作例

以下の各フレームは、この MCP を使って AI が完全に生成したもので、手動での配置は一切ありません。

E コマースプラットフォームのアーキテクチャ

決済処理フロー

ユースケース

• 新しいコードベースへのオンボーディング — サービスを指定するだけで、コードを1行も読むことなく高レベルのアーキテクチャ図を作成し、次に重要なフローのシーケンス図を作成できます。
• 設計ドキュメントと RFC — アーキテクチャのスケッチ、新しいライフサイクルのステートマシン、却下した選択肢を示すクアドラント、ロールアウト用のガントチャートを作成できます。1つのツールで、統一されたビジュアル言語を使えます。
• ランブックとインシデントの記録 — 起きたことを示すシーケンス図、発生時刻を示すタイムライン、誰が何をしたかを示すスイムレーンを作成できます。
• データプラットフォームのドキュメント — メダリオン階層、ロール別のパイプライン、インテグレーションのトポロジーを記録できます。
• BI ツールを使わないレポート — アーキテクチャ図と並べても違和感のない、手描き風の棒グラフ、折れ線グラフ、散布図を作成できます。
• 更新し続けられるドキュメント — .excalidraw ファイルをコミットし、システムの変更に合わせて自然言語で改訂できます。6スプリント前の古い図が残ることはありません。

クイックスタート

インストール

pip install excalidraw-architect-mcp

PNG エクスポートをサポートするには（SVG はそのまま使用できます）。

pip install excalidraw-architect-mcp[png]

インストールせずに実行することもできます（uv が必要です）。

uvx excalidraw-architect-mcp

IDE で MCP を設定する

Cursor — .cursor/mcp.json に追加します。

{
  "mcpServers": {
    "excalidraw-architect": {
      "command": "excalidraw-architect-mcp",
      "transport": "stdio"
    }
  }
}

Claude Code — 次のワンライナーを実行します。

claude mcp add-json excalidraw-architect '{"type":"stdio","command":"excalidraw-architect-mcp"}' --scope user

または、プロジェクトのルートにある .mcp.json に手動で追加します。

{
  "mcpServers": {
    "excalidraw-architect": {
      "type": "stdio",
      "command": "excalidraw-architect-mcp"
    }
  }
}

Windsurf / その他の IDE — 同じ方法で、stdio 経由の excalidraw-architect-mcp コマンドを指定します。

Excalidraw Architect Skill をインストールする（25種類のタイプを使う場合に推奨）

skills/excalidraw-architect/ は、AI が25種類のタイプのどれを選ぶべきか、また1つの図にどれだけの情報を盛り込むかを判断できるようにします。選択表、密度の上限、アクセントカラーの予約ルール、各 spec の具体例を学習できます。

ln -s "$PWD/skills/excalidraw-architect" ~/.claude/skills/excalidraw-architect

同じガイダンスは list_diagram_types() と get_diagram_schema() を通じてサーバーにも含まれているため、Cursor、Windsurf、Zed では何もインストールせずに利用できます。Skill を使うと、次の呼び出しを待たず、最初からその内容をコンテキストに加えられます。どちらも単一のソース（src/excalidraw_mcp/diagrams/registry.py）から生成されており、内容にずれが生じるとテストでビルドが失敗します。

Diagram Design Skill をインストールする（推奨）

このリポジトリには Diagram Design Skill が含まれており、最適な結果を得るための図の構成方法（ノード数の上限、トポロジーのルール、エッジラベルのガイドライン、一般的なパターン）を AI に教えます。

Cursor ユーザーの場合：

mkdir -p ~/.cursor/skills/excalidraw-diagram-design && \
curl -o ~/.cursor/skills/excalidraw-diagram-design/SKILL.md \
  https://raw.githubusercontent.com/BV-Venky/excalidraw-architect-mcp/main/.skills/excalidraw-diagram-design/SKILL.md

その他の IDE の場合： SKILL.md ファイルをダウンロードし、IDE のプロンプトコンテキストまたはシステム指示に追加してください。

AI はこのスキルを自動的に認識し、図の生成時に適用します。ルールは自由に変更して、好みに合わせることができます。ノード数の上限を調整したり、独自のパターンを追加したり、スタイルのガイドラインを変更したりしてください。

Knowledge Graph Skill をインストールする（グラフのワークフローに推奨）

architecture knowledge graph 用に、このリポジトリには Architecture Knowledge Graph Skill も含まれています。このスキルは、コードベースを適切に読み取る方法を AI に教えます。サービスの境界を特定し、通信シグナル（HTTP / gRPC / Kafka / DB）を適切なラベル付きリンクに対応付け、複数のリポジトリ間でプロデューサーとコンシューマーを照合し、グラフを見やすく保つ方法（安定した ID、すべてのエッジへのラベル付け、レンダリング前の lint）を学習します。

Cursor ユーザーの場合：

mkdir -p ~/.cursor/skills/architecture-knowledge-graph && \
curl -o ~/.cursor/skills/architecture-knowledge-graph/SKILL.md \
  https://raw.githubusercontent.com/BV-Venky/excalidraw-architect-mcp/main/.skills/architecture-knowledge-graph/SKILL.md

その他の IDE の場合： SKILL.md ファイルをダウンロードし、IDE のプロンプトコンテキストまたはシステム指示に追加してください。

図の複雑さに関する注意： コンポーネントや接続の数が増えるほど、図は必然的に読みにくくなります。これは自動レイアウトだけでなく、人が手作業で描く場合も同じです。最適な結果を得るには、アーキテクチャ図では6～15 個のノード、詳細なフローでは10～25 個のノードを目安にしてください。システムがそれより大きい場合は、すべてを 1 つに詰め込まず、複数の目的別の図に分割してください。

使い方

AI IDE に自然な言葉で指示するだけです。

「このコードベースの高レベルなアーキテクチャ図を作成して」

「API Gateway、Auth Service、User Service、Order Service、PostgreSQL、Redis キャッシュ、Kafka イベントバスを含むマイクロサービスシステムのアーキテクチャ図を作成して」

「この mermaid 図を excalidraw 図に変換して」

「高レベルアーキテクチャ図の Order Service にキャッシュレイヤーを追加して」

「アーキテクチャ図を SVG にエクスポートして」

「図を解像度 3x の PNG としてエクスポートして」

AI は関係マップを指定して MCP ツールを呼び出します。MCP がレイアウト、スタイル設定、出力を処理します。生成された .excalidraw ファイルを Excalidraw VS Code extension で開くか、excalidraw.com にドラッグしてください。

機能

自動レイアウトエンジン

Sugiyama 階層レイアウトアルゴリズムを使用し、以下の機能を備えています。

• 適応型レイヤー間隔 - エッジラベルの長さに応じて間隔を調整します
• ハブノードの伸長 - ゲートウェイ／ロードバランサーを、接続されたサービス全体にまたがるように伸長します
• 障害物を考慮したエッジルーティング - 矢印が中間ノードを貫通せず、その周囲をカーブして通ります
• 非接続コンポーネントの配置 - 監視スタックなどの個別のサブグラフを、重ならないように配置します

コンポーネントライブラリ

50 種類以上のテクノロジーに対応したマッピングと、自動スタイル設定を利用できます。

カテゴリ	テクノロジー
データベース	PostgreSQL、MySQL、MongoDB、DynamoDB、Cassandra、ClickHouse、SQLite、CockroachDB
メッセージキュー	Kafka、RabbitMQ、SQS、Redis Streams、NATS
キャッシュ	Redis、Memcached、Varnish
ロードバランサー	Nginx、HAProxy、ALB/ELB、Traefik、Envoy
コンピューティング	Docker、Kubernetes、Lambda、ECS、Fargate
ストレージ	S3、GCS、Azure Blob、MinIO
API	REST、GraphQL、gRPC、WebSocket
CDN	CloudFront、Cloudflare
監視	Prometheus、Grafana、Datadog、ELK
クライアント	ブラウザー、モバイル、デスクトップ、CLI

ステートフルな編集

図のメタデータは .excalidraw ファイルに埋め込まれています。AI に次のように依頼します。

「既存の図で、データベースの前に Redis キャッシュを追加してください」

MCP は現在の状態を読み取り、変更を適用して、適切なレイアウトで再レンダリングします。

Mermaid からの変換

Mermaid のフローチャートをすでにお持ちですか？ 変換できます。

「この Mermaid 図を Excalidraw に変換してください」（Mermaid の構文を貼り付けます）

手描き風の見た目を保った画像のエクスポート

Excalidraw のスケッチ風の見た目はファイルに保存されているのではなく、レンダリング時に roughjs によって生成されます。roughjs は各図形を、その要素をシードとして揺らぎを加えた2本のストロークで描き直します。単純な <rect> を出力するエクスポーターでは、形状を正確に再現できても、手描きらしさはまったく再現できません。

そこで、このエクスポーターでは roughjs のストローク生成処理を Python に移植しています。同じシード付き PRNG、同じ線・曲線・楕円・塗りつぶしの処理を使用します。エクスポート結果はキャンバスと同じように、二重の鉛筆ストローク、はみ出した円、V 字型の矢印の先端、輪郭線よりわずかに内側に収まる塗りつぶしを再現します。

• SVG — 追加の依存関係は不要です。ブラウザーも Node.js も必要ありません
• PNG — オプションの cairosvg パッケージが必要です（pip install excalidraw-architect-mcp[png]）。解像度の倍率を設定できます（デフォルトは 2×）

Chrome では意図的に鮮明に描画します。軸、グリッド線、レーンの区切り線には roughness: 0 を設定しています。手描き風の揺らぎを加えた1pxの細線は、ノイズと見分けがつかないためです。

フォント。 Excalidraw の Excalifont は同梱の Web フォントであるため、単体の SVG では代替先がありません。エクスポートでは、汎用 CSS の cursive ではなく、実際の手書き風フォントを優先順に指定します（Excalifont → Virgil → Segoe Print → Bradley Hand → Chalkboard）。macOS では cursive がカリグラフィー風の Apple Chancery に解決されます。どの環境でも同じ見た目の出力にするには、フォントファイルを渡して埋め込みます。

export_to_svg("arch.excalidraw", "arch.svg", embed_font="Excalifont.woff2")

「アーキテクチャ図を SVG としてエクスポートしてください」

MCP ツール

図のツール

ツール	説明
create_diagram	対応する25種類の中から、任意の種類の図を作成します
list_diagram_types	各種類の用途と、使用する場合・しない場合の指針を確認できます
get_diagram_schema	1種類の仕様スキーマと、記述例を確認できます
mermaid_to_excalidraw	Mermaid のフローチャート構文を .excalidraw に変換します
modify_diagram	既存の図を修正します。ノードや接続、または保存済みの仕様を対象にできます
get_diagram_info	現在の図の状態を読み取ります（変更前に呼び出してください）
export_diagram	.excalidraw を SVG または PNG 画像としてエクスポートします

ナレッジグラフツール（kg_*）

任意です。アーキテクチャ文書化ワークフロー専用です。ナレッジグラフ（デフォルトは .claude/architecture.md）が信頼できる唯一の情報源となり、図はそのレンダリングビューになります。詳しくは、以下のアーキテクチャナレッジグラフをご覧ください。

ツール	説明
kg_init	新しいナレッジグラフファイルを作成します
kg_add_service / kg_remove_service	サービスを追加・更新、または削除します（タイプ、ドメイン、担当者、タグ、リンクを含む）
kg_link / kg_unlink	依存関係を追加・削除します（並列エッジに対応。例：同じペア間の REST と Kafka）
kg_set_domain	サービスをドメイン／境界づけられたコンテキストにグループ化します
kg_info	サービス、ドメイン、トポロジーを要約します
kg_render	アーキテクチャ全体を .excalidraw にレンダリングします
kg_render_view	指定したサービスに焦点を当てた図をレンダリングします
kg_render_around	サービスから N ホップ以内のすべてをレンダリングします
kg_render_domain	単一のドメインをレンダリングします
kg_import	既存の .excalidraw 図からグラフを作成します
whats_connected_to	影響分析 — 上流／下流への影響範囲を調べます
kg_path	2 つのサービス間の依存関係の経路をたどります
kg_lint	ヘルスチェック：循環依存、単一障害点、孤立したサービス、参照切れを検出します
kg_export	グラフを Mermaid、Graphviz DOT、または JSON にエクスポートします
kg_diff	git の参照以降にアーキテクチャがどう変化したかを表示します
kg_onboarding_doc	グラフから人間向けのオンボーディングガイドを生成します
kg_drift	宣言されたグラフと Python のインポートとのずれを検出します

🧠 アーキテクチャナレッジグラフ

任意で、アーキテクチャ専用です。 上記の機能はすべて、これがなくても動作します。ただし、同じシステムを繰り返し文書化する場合、一度作成した図は閉じた瞬間に古くなってしまいます。そこでアーキテクチャ図を、AI が一度構築し、あらゆる場面で再利用する、永続的でバージョン管理されたモデルのビューとして扱うことができます。

上の図は、単一の .claude/architecture.md ファイルであるナレッジグラフからレンダリングされました。Order Service → Payment Service が 2 回登場していることに注目してください。実線は REST /charge の呼び出し、破線は Kafka payment.requested イベントです。2 種類の通信方式に、2 本の矢印があります。

ナレッジグラフを使う理由

一度作成した図は、閉じた瞬間に古くなってしまいます。ナレッジグラフは、常に更新されるモデルです。

• 1 つの信頼できる情報源から、多くのビューを作成 — システム全体を一度保存すれば、全体像、単一のドメイン、または 1 つのサービスから N ホップ以内のすべてをレンダリングできます。
• 図全体で一貫性を維持 — 同じサービスは、どの図でも同じ ID、スタイル、メタデータを保ちます。
• クエリ可能 — 「決済が停止したら何が壊れる？」と尋ねれば、推測ではなく実際の影響範囲がわかります。
• 自己チェック機能 — 依存関係の循環、単一障害点、孤立したサービスをチェックできます。
• git で管理 — PR でアーキテクチャの変更をレビューでき、Markdown の差分も見やすくなります。

人間にも機械にも読み取れるファイル

グラフは単一の Markdown ファイルです（デフォルトは .claude/architecture.md）。

## Services
- order-service: Order Service [type: service] [domain: orders] [owner: @orders]
- payment-service: Payment Service [type: service] [domain: payments] [owner: @payments]

## Dependencies
- order-service -> payment-service : "REST /charge"
- order-service -> payment-service : "Kafka payment.requested" [style: dashed]

手作業で編集することも、AI に管理させることもできます。どちらの場合も、情報を損なわずに相互変換できます。

AI に尋ねるだけ

「このコードベースをアーキテクチャナレッジグラフにマッピングして」

「Kafka 経由で order サービスを payments に接続して」

「payment サービスに依存しているものは？その周辺だけを図にして」

「orders ドメインを焦点を絞った図としてレンダリングして」

「循環依存と単一障害点がないか、アーキテクチャをチェックして」

「既存の diagram.excalidraw をナレッジグラフにインポートして」

「アーキテクチャからオンボーディングガイドを生成して」

すべてのツールについては、ナレッジグラフツールをご覧ください。

コントリビューション

詳しくは CONTRIBUTING.md をご覧ください。

ライセンス

MIT - 詳しくは LICENSE をご覧ください。