Excalidraw Architect MCP
Turn architecture into a queryable knowledge graph and render auto-laid-out Excalidraw diagrams. Offline, no API keys.
Add to your client
Copy the config for your MCP client and paste it into its config file.
pip install excalidraw-architect-mcpPaste into ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"excalidraw-architect-mcp": {
"command": "excalidraw-architect-mcp",
"args": []
}
}
}Step-by-step guides: Add to Claude Desktop · Add to Cursor · Add to Windsurf
Before you start
- Python with pip (or uv/uvx to run without installing)
- An MCP-compatible IDE (Cursor, Claude Code, Windsurf)
- Optional: cairosvg for PNG export (pip install excalidraw-architect-mcp[png])
- Optional: Excalidraw VS Code extension or excalidraw.com to view .excalidraw files
About Excalidraw Architect MCP
An MCP server that separates diagram structure from layout: the LLM describes components and connections, and the server applies a Sugiyama hierarchical layout, architecture-aware styling for 50+ technologies, and obstacle-aware edge routing to produce clean Excalidraw diagrams. It also maintains a persistent architecture knowledge graph in a single human- and machine-readable markdown file, which acts as the source of truth — diagrams are rendered views that can cover the full system, a focused set of services, a single domain, or a service's N-hop neighborhood. Additional tools support Mermaid conversion, stateful editing, impact analysis, linting, drift detection, and export to SVG/PNG/Mermaid/Graphviz/JSON. It runs fully offline in Cursor, Claude Code, and Windsurf with no API keys.
Tools & capabilities (24)
create_diagramCreate a new diagram from structured node/connection data.
mermaid_to_excalidrawConvert Mermaid flowchart syntax to a .excalidraw file.
modify_diagramAdd/remove/update nodes and connections on an existing diagram.
get_diagram_infoRead current diagram state (call before modifying).
export_diagramExport a .excalidraw file to an SVG or PNG image.
kg_initCreate a new knowledge graph file.
kg_add_serviceAdd or update a service (with type, domain, owner, tags, links).
kg_remove_serviceRemove a service from the knowledge graph.
kg_linkAdd a dependency between services (parallel edges supported, e.g. REST and Kafka between the same pair).
kg_unlinkRemove a dependency between services.
kg_set_domainGroup a service into a domain / bounded context.
kg_infoSummarize services, domains, and topology.
kg_renderRender the whole architecture to a .excalidraw file.
kg_render_viewRender a focused diagram of specific services.
kg_render_aroundRender everything within N hops of a service.
kg_render_domainRender a single domain.
kg_importBootstrap the knowledge graph from an existing .excalidraw diagram.
whats_connected_toImpact analysis — upstream/downstream blast radius for a service.
kg_pathTrace the dependency path between two services.
kg_lintHealth check: cycles, single points of failure, orphans, dangling refs.
kg_exportExport the graph to Mermaid, Graphviz DOT, or JSON.
kg_diffShow how the architecture changed since a git ref.
kg_onboarding_docGenerate a human onboarding guide from the graph.
kg_driftDetect drift between the declared graph and Python imports.
When to use it
- Onboarding onto a new codebase — point it at a microservice and get a high-level architecture diagram without reading code.
- Brainstorming and system design — whiteboard a new service and iterate with natural language ("add a cache here", "swap Kafka for SQS").
- Documentation that stays alive — keep a .excalidraw file in the repo and update it with natural language as the system evolves.
- Maintaining a living architecture knowledge graph in git, reviewable in PRs as clean markdown diffs.
- Impact analysis — query the blast radius of a failing service before making changes.
- Converting existing Mermaid flowcharts into editable Excalidraw diagrams.
Security notes
Runs fully offline over stdio with no API keys or network calls. The server reads and writes `.excalidraw` and `.claude/architecture.md` files on the local filesystem. Optional PNG export requires the extra `cairosvg` dependency (`pip install excalidraw-architect-mcp[png]`).
Excalidraw Architect MCP FAQ
Does it require API keys or network access?
No. It runs fully offline over stdio in Cursor, Claude Code, and Windsurf with no API keys.
How do I export diagrams to images?
SVG export works out of the box via a pure-Python renderer (no browser needed). PNG export requires the optional cairosvg dependency: pip install excalidraw-architect-mcp[png], and supports a configurable resolution multiplier (default 2x).
What is the architecture knowledge graph?
A persistent, version-controlled model of your system stored in a single markdown file (default .claude/architecture.md). It is the source of truth, and diagrams are rendered views — full system, a domain, or a service's N-hop neighborhood. It round-trips losslessly whether edited by hand or by the AI.
How many nodes should a diagram have?
For readability, aim for 6-15 nodes in architecture diagrams and 10-25 in detailed flows. Larger systems should be split into multiple focused diagrams.
Alternatives to Excalidraw Architect MCP
Compare all alternatives →
Popular community server that feeds Figma layout data to coding agents via a Figma API token.
Generate beautiful, modern UI components from natural-language descriptions inside your IDE.
Give AI assistants full access to shadcn/ui v4 components, blocks, demos, and metadata across React, Svelte, Vue, and React Native.
Compare Excalidraw Architect MCP with: