Excalidraw Architect

Excalidraw Architect MCP

[PyPI] [Cursor Directory] [License: MIT] [PyPI Downloads]

Every diagram your engineering docs need — as hand-drawn Excalidraw, generated by your AI.

Twenty-five diagram types. Architecture and flowcharts, but also sequence diagrams, state machines, ER models, swimlanes, timelines, Gantt charts, quadrants, funnels, and hand-sketched bar/line/scatter charts. No coordinates to hallucinate, no Figma, no stale PNGs.

The Problem

When you're onboarding onto a codebase, designing a new system, or documenting how something works, a diagram communicates in seconds what pages of text can't. But the options aren't great.

Mermaid is quick to generate and locked down — you can't drag a node, group things visually, or annotate it afterwards. Figma means thirty minutes of manual work per picture. And when an LLM writes Excalidraw JSON directly it hallucinates coordinates: boxes overlap, arrows tangle, and you fix it by hand.

Worse, most tools only cover one diagram type well. The moment your doc needs a sequence diagram next to the architecture sketch, you're switching tools and the two look nothing alike.

The Solution

excalidraw-architect-mcp separates the what from the where — the AI describes structure, the engine does the pixel math.

Your LLM says what the components, actors, tiers, or data points are. The MCP picks the layout algorithm for that diagram type, styles it, and writes a real .excalidraw file you can open and keep editing. 50+ technologies (Kafka, PostgreSQL, Redis…) get auto-styled, every diagram can be revised in natural language, and it runs fully offline in Cursor/Claude Code/Windsurf — no API keys.

• 25 diagram types, one grammar — see them all, from architecture to Gantt to scatter plots
• Genuinely hand-drawn output — a pure-Python port of the roughjs stroke generator, so exported SVG/PNG looks like the Excalidraw canvas, not a clean-geometry approximation
• Perfect layouts every time — Sugiyama with adaptive spacing for graphs; purpose-built geometry for everything else
• Architecture-aware styling — say "Kafka" and get a stream-styled node, not a generic rectangle
• Talk to your diagrams — add, remove, or rewire any diagram in natural language; the spec lives in the file
• Export to SVG & PNG — no browser, no Node.js
• Living architecture knowledge graph — optionally persist your system as a version-controlled model the AI can query and lint (details)

📐 25 Diagram Types

Every image below is a real .excalidraw file generated by this MCP — zero manual positioning. Click any one to see it full size.

Choosing and calling

The gallery above is ordered by how often you'll reach for each type. Internally they fall into five families, which is what decides the layout engine:

architecture and flowchart are graphs and take nodes + connections. Every other type takes a diagram_type and a spec shaped for it:

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},        ],    },)

Call list_diagram_types() for when-to-use guidance on each, and get_diagram_schema("<type>") for the exact spec shape. Or just ask: "draw the PR review flow as a swimlane".

Two conventions worth knowing. Mark one or two elements "focal": true — that earns the accent color, and marking five spends the signal. And chrome (axes, gridlines, lane dividers) deliberately renders crisp while shapes and data marks render hand-drawn; that contrast is what keeps a sketchy chart legible instead of noisy.

Editing works on every type. The validated spec is stored inside the .excalidraw file, so you patch it rather than rebuild it:

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

Lists are replaced wholesale — to change one tier, send the whole tiers list.

Regenerate every image above with python scripts/generate_showcase.py --png.

See It In Action

Every frame below is generated entirely by AI using this MCP - zero manual positioning.

E-Commerce Platform Architecture

[E-Commerce Platform Demo]

Payment Processing Flow

[Payment Processing Flow Demo]

Use Cases

• Onboarding onto a new codebase — point it at a service and get a high-level architecture diagram without reading a line of code, then a sequence diagram for the one flow that matters.
• Design docs and RFCs — an architecture sketch, a state machine for the new lifecycle, a quadrant for the options you rejected, and a Gantt for the rollout. One tool, one visual language.
• Runbooks and incident write-ups — sequence diagrams for what happened, timelines for when, swimlanes for who did what.
• Data platform documentation — medallion tiers, role-scoped pipelines, integration topology.
• Reporting without a BI tool — hand-drawn bar/line/scatter charts that sit next to your architecture diagram instead of clashing with it.
• Documentation that stays alive — commit the .excalidraw file and revise it in natural language as the system changes. No more stale diagrams from six sprints ago.

Quick Start

Install

pip install excalidraw-architect-mcp

For PNG export support (SVG works out of the box):

pip install excalidraw-architect-mcp[png]

Or run without installing (requires uv):

uvx excalidraw-architect-mcp

Configure MCP in Your IDE

Cursor - Add to .cursor/mcp.json:

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

Claude Code - Run this one-liner:

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

Or add manually to .mcp.json in your project root:

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

Windsurf / Other IDEs - Same pattern; point to the excalidraw-architect-mcp command over stdio.

Install the Excalidraw Architect Skill (recommended for the 25 types)

skills/excalidraw-architect/ teaches the AI which of the 25 types to pick and how much to put in one — the selection table, the density budget, the reserved-accent rule, and a worked example of every spec.

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

The same guidance also ships inside the server via list_diagram_types() and get_diagram_schema(), so Cursor, Windsurf, and Zed get it without installing anything — the skill just puts it in context up front instead of one call later. Both are generated from a single source (src/excalidraw_mcp/diagrams/registry.py); a test fails the build if they drift.

Install the Diagram Design Skill (recommended)

This repo includes a Diagram Design Skill that teaches the AI how to structure diagrams for the best results - node count limits, topology rules, edge label guidelines, and common patterns.

For Cursor users:

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

For other IDEs: Download the SKILL.md file and add it to your IDE's prompt context or system instructions.

The AI will automatically pick up the skill and apply it when generating diagrams. Feel free to modify the rules to suit your preferences - tweak node limits, add your own patterns, or adjust styling guidelines.

Install the Knowledge Graph Skill (recommended for the graph workflow)

For the architecture knowledge graph, this repo also includes an Architecture Knowledge Graph Skill. It teaches the AI how to read a codebase well — identify service boundaries, map communication signals (HTTP / gRPC / Kafka / DB) to the right labelled links, match producers and consumers across repos, and keep the graph clean (stable ids, every edge labelled, lint before render).

For Cursor users:

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

For other IDEs: Download the SKILL.md file and add it to your IDE's prompt context or system instructions.

A note on diagram complexity: As the number of components and connections grows, diagrams inevitably become harder to read - this is true for humans drawing by hand too, not just automated layout. For best results, aim for 6-15 nodes in architecture diagrams and 10-25 nodes in detailed flows. If your system is larger, split it into multiple focused diagrams rather than cramming everything into one.

Use It

Just ask your AI IDE naturally:

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

The AI calls the MCP tool with the relationship map. The MCP handles layout, styling, and output. Open the resulting .excalidraw file with the Excalidraw VS Code extension or drag it into excalidraw.com.

Features

Auto Layout Engine

Uses the Sugiyama hierarchical layout algorithm with:

• Adaptive layer gaps - spacing adjusts based on edge label length
• Hub node stretching - gateways/load balancers stretch to span connected services
• Obstacle-aware edge routing - arrows curve around intermediate nodes instead of cutting through them
• Disconnected component stacking - separate subgraphs (e.g., monitoring stack) are placed without overlap

Component Library

50+ technology mappings with automatic visual styling:

Stateful Editing

Diagram metadata is embedded in the .excalidraw file. Ask the AI:

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

The MCP reads the current state, applies the modification, and re-renders with proper layout.

Mermaid Conversion

Already have a Mermaid flowchart? Convert it:

"Convert this Mermaid diagram to Excalidraw" (paste your Mermaid syntax)

Image Export That Still Looks Hand-Drawn

Excalidraw's sketchy look is not stored in the file — it is produced at render time by roughjs, which redraws every shape as two jittered strokes seeded from the element. An exporter that emits a plain <rect> reproduces the geometry perfectly and the character not at all.

So this one ports the roughjs stroke generator to Python: same seeded PRNG, same line/curve/ellipse/fill routines. Exports match the canvas — doubled pencil strokes, overshooting circles, V-shaped arrowheads, and fills that sit slightly inside their outlines.

• SVG — zero extra dependencies, no browser, no Node.js
• PNG — requires the optional cairosvg package (pip install excalidraw-architect-mcp[png]); configurable resolution multiplier (default 2×)

Chrome renders crisp on purpose. Axes, gridlines, and lane dividers are drawn at roughness: 0, because a 1px hairline with hand-drawn jitter is indistinguishable from noise.

Fonts. Excalidraw's Excalifont is a bundled webfont, so a standalone SVG has nothing to resolve it to. Exports name a stack of real handwriting faces (Excalifont → Virgil → Segoe Print → Bradley Hand → Chalkboard) instead of the generic CSS cursive, which on macOS resolves to the calligraphic Apple Chancery. For output that looks identical everywhere, pass a font file to embed it:

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

"Export the architecture diagram as an SVG"

MCP Tools

Diagram tools

Knowledge graph tools (kg_*)

Optional. For the architecture-documentation workflow only — the knowledge graph (default .claude/architecture.md) becomes the source of truth and diagrams become rendered views of it. See Architecture Knowledge Graph below.

🧠 Architecture Knowledge Graph

Optional, and only for architecture. Everything above works without it. But if you document one system repeatedly, a one-off diagram goes stale the moment you close it — so architecture diagrams can instead be views of a persistent, version-controlled model the AI builds once and reuses everywhere.

[Knowledge Graph rendered diagram]

The diagram above was rendered from a knowledge graph — a single .claude/architecture.md file. Notice Order Service → Payment Service appears twice: a solid REST /charge call and a dashed Kafka payment.requested event. Two communication modes, two arrows.

Why a knowledge graph?

A one-off diagram goes stale the moment you close it. A knowledge graph is a living model:

• One source of truth, many views — store the whole system once, then render the full picture, a single domain, or everything within N hops of one service.
• Consistent across diagrams — the same service keeps the same id, styling, and metadata everywhere.
• Queryable — ask "what breaks if payments goes down?" and get the real blast radius, not a guess.
• Self-checking — lint for dependency cycles, single points of failure, and orphaned services.
• Lives in git — review architecture changes in PRs; the markdown diffs cleanly.

The file is human- and machine-readable

The graph is a single markdown file (default .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]

Edit it by hand or let the AI maintain it — it round-trips losslessly either way.

Just ask your AI

"Map this codebase into the architecture knowledge graph"

"Link the order service to payments over Kafka"

"What depends on the payment service? Render just its neighborhood"

"Render the orders domain as a focused diagram"

"Lint the architecture for cycles and single points of failure"

"Import my existing diagram.excalidraw into the knowledge graph"

"Generate an onboarding guide from the architecture"

See the Knowledge Graph tools for the full tool list.

Contributing

See CONTRIBUTING.md for details.

License

MIT - see LICENSE.