Excalidraw Architect MCP

馴染みのない複雑なコードベースを理解しようとすることは、常に苦労の連続です。認知負荷を管理し、すべてがどのように組み合わさっているかを想像しようとすることに疲弊してしまいます。

問題点

コードベースへのオンボーディング、新しいシステムの設計、または既存のアーキテクチャのドキュメント作成を行う際、視覚的な図は、何ページものテキストでは伝えられないことを一瞬で伝えてくれます。しかし、現在の選択肢はあまり優れていません。Mermaid図は生成が早いものの機能が限定的で、ノードをドラッグして再配置したり、コンポーネントを視覚的にグループ化したりすることはできません。Excalidrawはこれらの問題を解決しますが、LLMが直接Excalidrawを生成しようとすると座標をハルシネーション（幻覚）してしまい、ボックスが重なったり、矢印が絡まったりして、結局手動で図を修正することになります。

Related MCP server: Excalidraw MCP App

解決策

excalidraw-architect-mcpは、「何（what）」と「どこ（where）」を分離します。AIは構造に集中し、エンジンがピクセル計算を処理します。

LLMがコンポーネントと接続を記述し、MCPが適切なグラフレイアウトアルゴリズムを使用してレイアウト、スタイリング、レンダリングを処理します。50以上のテクノロジー（Kafka、PostgreSQL、Redisなど）が自動的にスタイリングされ、自然言語で図を反復的に編集でき（「DBの前にキャッシュを追加して」など）、CursorやWindsurf内で完全にオフラインで動作するため、APIキーは不要です。

• 常に完璧なレイアウト - 適応型間隔を備えた杉山アルゴリズムにより、ボックスの重なりがありません

• アーキテクチャを意識したスタイリング - 「Kafka」と指定すれば、一般的な長方形ではなく、ストリーム形式のノードが生成されます

• 図との対話 - 自然言語を使用して、既存の図のコンポーネントを追加、削除、または再配線できます

• ハブノードの可視化 - ゲートウェイやロードバランサーは、接続されたサービスに合わせて自動的に伸縮します

• SVGおよびPNGへのエクスポート - ブラウザ不要で、あらゆる .excalidraw ファイルをポータブルな画像に変換します

動作の様子

以下の各フレームは、このMCPを使用してAIによって完全に生成されたもので、手動での配置は一切行われていません。

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

決済処理フロー

ユースケース

• 新しいコードベースへのオンボーディング - マイクロサービスを指定すれば、コードを一行も読まずに高レベルなアーキテクチャ図を取得できます。詳細が必要な場合は、クラスのセットを指定して低レベルなフロー図を作成できます。

• ブレインストーミングとシステム設計 - 新しいサービスをホワイトボードに描いたり、トレードオフを議論したりする際に、進捗に合わせてアーキテクチャを可視化させます。「ここにキャッシュを追加して」や「KafkaをSQSに置き換えて」と指示するだけで、ゼロから描き直すことなく反復作業が可能です。

• 常に最新のドキュメント - .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 コマンドを指定してください。

Diagram Design Skillのインストール（推奨）

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

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は自動的にこのスキルを読み取り、図を生成する際に適用します。ノード制限の調整、独自のパターンの追加、スタイリングガイドラインの変更など、好みに合わせてルールを自由に修正してください。

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

使用方法

AI IDEに自然に尋ねるだけです：

"Create a high-level architecture diagram of this codebase"

"Create an architecture diagram for a microservices system with an API Gateway, Auth Service, User Service, Order Service, PostgreSQL, Redis cache, and Kafka event bus"

"Convert this mermaid diagram to excalidraw diagram"

"Add a Caching layer to the Order Service in the High Level architecture diagram"

"Export the architecture diagram to SVG"

"Export the diagram as a PNG at 3x resolution"

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

機能

自動レイアウトエンジン

杉山階層レイアウトアルゴリズムを使用：

• 適応型レイヤーギャップ - エッジラベルの長さに応じて間隔を調整

• ハブノードの伸縮 - ゲートウェイ/ロードバランサーが接続されたサービスに合わせて伸縮

• 障害物を考慮したエッジルーティング - 矢印が中間ノードを突き抜けるのではなく、避けて曲線を描く

• 切断されたコンポーネントのスタッキング - 個別のサブグラフ（例：監視スタック）を重なりなしで配置

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

50以上のテクノロジーマッピングと自動視覚スタイリング：

ステートフルな編集

図のメタデータは .excalidraw ファイルに埋め込まれています。AIに次のように指示してください：

"Add a Redis cache in front of the database in the existing diagram"

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

Mermaid変換

すでにMermaidフローチャートをお持ちですか？変換可能です：

"Convert this Mermaid diagram to Excalidraw" (Mermaid構文を貼り付け)

画像エクスポート

あらゆる .excalidraw 図をポータブルな画像にエクスポートできます。ブラウザ、Excalidrawアプリ、Node.jsは不要です。

• SVG - 追加の依存関係なし。長方形、楕円、ひし形、テキスト（複数行含む）、矢印（矢印ヘッド付き）を処理する純粋なPythonレンダラーを使用

• PNG - オプションの cairosvg パッケージ (pip install excalidraw-architect-mcp[png]) が必要。設定可能な解像度倍率（デフォルト2倍）をサポート

"Export the architecture diagram as an SVG"

MCPツール

コントリビューション

詳細は CONTRIBUTING.md を参照してください。

ライセンス

MIT - LICENSE を参照してください。