excalidraw-architect-mcp
Excalidraw Architect MCP
馴染みのない複雑なコードベースを理解しようとすることは、常に苦労の連続です。認知負荷を管理し、すべてがどのように組み合わさっているかを想像しようとすることに疲弊してしまいます。
問題点
コードベースへのオンボーディング、新しいシステムの設計、または既存のアーキテクチャのドキュメント作成を行う際、視覚的な図は、何ページものテキストでは伝えられないことを一瞬で伝えてくれます。しかし、現在の選択肢はあまり優れていません。Mermaid図は生成が早いものの機能が限定的で、ノードをドラッグして再配置したり、コンポーネントを視覚的にグループ化したりすることはできません。Excalidrawはこれらの問題を解決しますが、LLMが直接Excalidrawを生成しようとすると座標をハルシネーション(幻覚)してしまい、ボックスが重なったり、矢印が絡まったりして、結局手動で図を修正することになります。
Related MCP server: mermaid-to-excalidraw-mcp
解決策
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-mcpPNGエクスポートサポート(SVGは標準で動作します)が必要な場合:
pip install excalidraw-architect-mcp[png]または、インストールせずに実行(uvが必要です):
uvx excalidraw-architect-mcpIDEで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以上のテクノロジーマッピングと自動視覚スタイリング:
カテゴリ | テクノロジー |
データベース | 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 |
クライアント | Browser, Mobile, Desktop, CLI |
ステートフルな編集
図のメタデータは .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ツール
ツール | 説明 |
| 構造化されたノード/接続データから新しい図を作成 |
| Mermaidフローチャート構文を |
| 既存の図のノードと接続を追加/削除/更新 |
| 現在の図の状態を読み取る(変更前に呼び出す) |
|
|
コントリビューション
詳細は CONTRIBUTING.md を参照してください。
ライセンス
MIT - LICENSE を参照してください。
Available Tools
26 toolscreate_diagramA
Create a new Excalidraw diagram of any supported type.
Two input modes:
Graph types (
architecture,flowchart) - passnodesandconnections. The tool handles layout, styling, and rendering; no coordinates needed.Typed diagrams (every other type) - pass
diagram_typeand aspecobject shaped for that type. Calllist_diagram_typesto choose a type andget_diagram_schemato see its spec shape.
Inputs: output_path (required), spec, nodes, theme, +3 more. Returns: result
export_diagramA
Export an .excalidraw file to SVG or PNG image.
Converts an existing .excalidraw diagram into a portable image file without requiring a browser or the Excalidraw application.
Inputs: input_path (required), output_path (required), scale, format. Returns: result
get_diagram_infoA
Get a structured summary of an existing Excalidraw diagram.
Call this BEFORE modify_diagram to understand what nodes and connections currently exist. The summary includes node ids, labels, component types, and the full connection topology.
Inputs: file_path (required). Returns: result
get_diagram_schemaA
Get the JSON schema and selection guidance for one diagram type.
Call this before passing a spec to create_diagram for a type you have
not used yet, so the payload matches on the first attempt.
Inputs: diagram_type (required). Returns: result
kg_add_serviceB
Add or update a service in the knowledge graph.
Inputs: id (required), tags, label, links, +6 more. Returns: result
kg_diffB
Show how the architecture changed since a git ref (default HEAD).
Compares the current knowledge file against its version at ref.
Inputs: ref, graph_path. Returns: result
kg_driftA
Detect drift between the declared architecture and Python imports under code_root.
Best-effort: treats each top-level package as a service and infers edges from imports. Reports undocumented and possibly-stale dependencies.
Inputs: code_root (required), graph_path. Returns: result
kg_exportC
Export the knowledge graph to another format.
Inputs: format, graph_path, output_path. Returns: result
kg_importB
Import an existing .excalidraw diagram's services into the knowledge graph.
Bootstraps the graph from diagrams you already created with this tool.
Inputs: excalidraw_path (required), graph_path. Returns: result
kg_infoA
Summarize the whole knowledge graph: services, domains, and topology.
Call this before mutating the graph to reason about current state.
Inputs: graph_path. Returns: result
kg_initB
Create a new architecture knowledge graph file (markdown).
The knowledge graph is the persistent source of truth for your system's services and dependencies. Diagrams are rendered from it.
Inputs: title, direction, overwrite, graph_path. Returns: result
kg_linkA
Add a directed dependency: from_id depends on / calls to_id.
Both services must already exist (add them with kg_add_service first).
style is one of solid/dashed/dotted/thick.
Inputs: to_id (required), from_id (required), label, style, +1 more. Returns: result
kg_lintA
Architecture health check: cycles, single points of failure, orphans, dangling references, and (optionally) unowned services.
Inputs: graph_path, check_owners. Returns: result
kg_onboarding_docC
Generate a human onboarding guide (entry points, hubs, domains) from the graph.
Inputs: graph_path, output_path. Returns: result
kg_pathC
Trace the shortest dependency path between two services.
Inputs: to_id (required), from_id (required), graph_path. Returns: result
kg_remove_serviceC
Remove a service and all dependencies touching it.
Inputs: id (required), graph_path. Returns: result
kg_renderC
Render the entire architecture to an .excalidraw file.
Inputs: output_path (required), theme, graph_path. Returns: result
kg_render_aroundB
Render a service plus everything within depth hops of it.
direction: "downstream" (its dependencies), "upstream" (its
dependents), or "both".
Inputs: depth (required), service_id (required), output_path (required), theme, +2 more. Returns: result
kg_render_domainC
Render only the services belonging to one domain.
Inputs: domain (required), output_path (required), theme, graph_path. Returns: result
kg_render_viewC
Render a focused diagram of just the given services (induced subgraph).
Inputs: node_ids (required), output_path (required), theme, graph_path. Returns: result
kg_set_domainC
Assign a service to a domain (optionally set the domain's display label).
Inputs: domain (required), service_id (required), label, graph_path. Returns: result
kg_unlinkC
Remove the dependency from_id -> to_id.
Inputs: to_id (required), from_id (required), graph_path. Returns: result
list_diagram_typesA
List every supported diagram type with guidance on when to use it.
Call this BEFORE create_diagram when the right diagram type isn't obvious. Picking the wrong type is the most common way a diagram fails - a swimlane drawn as a flowchart loses the handoffs that were the point.
Two rules worth applying whatever you pick:
Target density ~4/10. Above 9 nodes it is probably two diagrams.
Mark only 1-2 elements "focal": true. The accent color is a signal, and using it everywhere destroys it.
Returns: A table of type -> family, when to use it, and when not to.
Inputs: no named parameters. Returns: result
mermaid_to_excalidrawA
Convert Mermaid flowchart syntax into an Excalidraw diagram.
Supports the mermaid flowchart subset that AI agents commonly generate:
Directions: graph TD, LR, BT, RL
Node shapes: [text], {text}, ((text)), ([text])
Edge types: -->, ---, -.-> ==> with |label|
Subgraphs: subgraph Title ... end
Component types are auto-detected from node labels (e.g., a node labeled "PostgreSQL DB" automatically gets database styling).
Inputs: output_path (required), mermaid_syntax (required), theme. Returns: result
modify_diagramA
Modify an existing Excalidraw diagram created by this tool.
Supports iterative editing: add components, remove nodes, update labels, and rewire connections - without recreating the entire diagram.
IMPORTANT: Call get_diagram_info first to understand the current diagram state before making modifications.
For typed diagrams (sequence, pyramid, bar, swimlane, ...) there is a single operation:
{"op": "update_spec", "patch": {"tiers": [...], "title": "New title"}}The patch is deep-merged into the stored spec and the diagram re-rendered. Lists are replaced wholesale, so send the complete list to change one entry. The node/connection operations below apply to architecture and flowchart diagrams only.
Inputs: file_path (required), operations (required), theme. Returns: result
whats_connected_toA
Impact analysis: what breaks if service_id fails?
Reports direct dependents, the full transitive upstream blast radius, and what the service itself depends on.
Inputs: service_id (required), graph_path. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 26 tools
Most tools target clearly distinct operations, and descriptions separate KG management, diagram creation, and analysis queries well. The four kg_render* variants (full, domain, view, around) are close enough to cause some misselection risk, though each has a well-defined scope.
The kg_ prefix provides a strong, predictable pattern for graph operations, and most diagram tools use clear verb_noun names. Minor exceptions like whats_connected_to and mermaid_to_excalidraw break the pattern, but overall the naming is disciplined and readable.
At 26 tools, the server sits just above the heavy band, and the kg_render_domain/view/around trio could plausibly be consolidated into one parameterized render operation. The breadth is partly justified by spanning diagram authoring and knowledge-graph management, but the surface is still large.
The toolset covers the full lifecycle for both the knowledge graph and diagrams: init, add/update/remove, link/unlink, query, render, export, plus analysis features like lint, drift, diff, impact, and path tracing. The only missing operations are non-essential file-management tasks like deleting a rendered diagram.
Maintenance
Related MCP Connectors
Collaborative whiteboard MCP server — create objects, connectors, C4 diagrams, and manage boards
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
Create and edit architecture diagrams from your AI agent; get an SVG and a live editable canvas.
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
Related MCP Servers
- AlicenseAqualityCmaintenanceAn MCP server for Excalidraw diagram creation and headless rendering, enabling interactive canvas editing and automated SVG/PNG export via Playwright.41MIT
- AlicenseAqualityDmaintenanceMCP server that converts Mermaid diagrams to styled Excalidraw files, saving them directly to disk without token overhead.2MIT
- FlicenseAqualityBmaintenanceAn MCP server that generates standalone SVG architecture diagrams from text descriptions, running entirely on your machine with no dependencies or network access.8-
- AlicenseAqualityDmaintenanceMCP server for generating and editing architecture diagrams from natural language or code, supporting formats like Terraform, docker-compose, Kubernetes, SQL, Mermaid, and PlantUML.2MIT