excalidraw-architect-mcp is an MCP server that generates and edits professional Excalidraw architecture diagrams from structured descriptions or Mermaid syntax, automatically handling layout and styling so the AI doesn't need to specify coordinates.
Create new diagrams (
create_diagram): Provide nodes (with optional technology types like Kafka, PostgreSQL, Redis) and connections; the server generates a fully laid-out.excalidrawfile with auto-styling for 50+ technologies, adaptive spacing, and no overlapping elements.Convert Mermaid diagrams (
mermaid_to_excalidraw): Parse existing Mermaid flowchart syntax and convert it into a properly rendered Excalidraw file, with auto-detection of component types from node labels.Modify existing diagrams (
modify_diagram): Iteratively edit an existing.excalidrawfile by adding/removing nodes or connections and updating labels/types — without recreating the entire diagram from scratch. Metadata is embedded in the file to support natural language updates.Inspect diagram state (
get_diagram_info): Retrieve a structured summary of an existing diagram's nodes (ID, label, component type) and connection topology — useful before making modifications.Automatic layout: Uses the Sugiyama hierarchical algorithm with hub node stretching, obstacle-aware edge routing, and disconnected component stacking.
Theme & direction control: Choose from
default,dark, orcolorfulthemes and layout directions (LR,TD,BT,RL).Runs fully offline: No API keys required; integrates with Cursor, Windsurf, and other MCP-compatible IDEs via stdio.
Provides architecture-aware visual styling for ClickHouse database components within Excalidraw diagrams.
Provides architecture-aware visual styling for Cloudflare CDN components within Excalidraw diagrams.
Provides architecture-aware visual styling for Datadog monitoring components within Excalidraw diagrams.
Provides architecture-aware visual styling for Docker compute components within Excalidraw diagrams.
Generates, modifies, and manages Excalidraw diagrams with automated layout, stateful editing, and architecture-aware styling.
Provides architecture-aware visual styling for Grafana monitoring components within Excalidraw diagrams.
Provides specialized visual styling for GraphQL API components within architecture diagrams.
Provides architecture-aware visual styling and layout for Kubernetes compute components within Excalidraw diagrams.
Supports converting Mermaid flowchart syntax into Excalidraw diagrams.
Provides architecture-aware visual styling for MinIO storage components within Excalidraw diagrams.
Provides architecture-aware visual styling for MongoDB database components within Excalidraw diagrams.
Provides architecture-aware visual styling for MySQL database components within Excalidraw diagrams.
Provides architecture-aware visual styling for NGINX load balancer and proxy components within Excalidraw diagrams.
Provides architecture-aware visual styling for PostgreSQL database components within Excalidraw diagrams.
Provides architecture-aware visual styling for Prometheus monitoring components within Excalidraw diagrams.
Provides architecture-aware visual styling for RabbitMQ message queue components within Excalidraw diagrams.
Provides architecture-aware visual styling and layout for Redis cache and stream components within Excalidraw diagrams.
Provides architecture-aware visual styling for SQLite database components within Excalidraw diagrams.
Excalidraw Architect MCP
It's been a constant struggle trying to understand unfamiliar and complex codebases - managing cognitive overload and trying to imagine how everything fits together.
The Problem
When you're onboarding onto a codebase, designing a new system, or documenting existing architecture, a visual diagram communicates in seconds what pages of text can't. But the options today aren't great. Mermaid diagrams are quick to generate but have limited capabilities - you can't drag a node to reposition it, group components visually. Excalidraw solves these problems, but when LLMs try to generate Excalidraw directly, they hallucinate coordinates - boxes overlap, arrows tangle, and you end up fixing the diagram manually.
The Solution
excalidraw-architect-mcp separates the what from the where - the AI focuses on structure, the engine handles the pixel math.
Your LLM describes the components and connections, and the MCP handles layout, styling, and rendering using a proper graph layout algorithm. 50+ technologies (Kafka, PostgreSQL, Redis, etc.) get auto-styled, you can iteratively edit diagrams with natural language ("add a cache in front of the DB"), and it runs fully offline in Cursor/Windsurf - no API keys needed.
Perfect layouts every time - Sugiyama algorithm with adaptive spacing; no overlapping boxes
Architecture-aware styling - say "Kafka" and get a stream-styled node, not a generic rectangle
Talk to your diagrams - add, remove, or rewire components on an existing diagram with natural language
Hub node visualization - gateways and load balancers auto-stretch to span their connected services
See It In Action
Every frame below is generated entirely by AI using this MCP - zero manual positioning.
E-Commerce Platform Architecture
Payment Processing Flow
Use Cases
Onboarding onto a new codebase - point it at a microservice and get a high-level architecture diagram without reading a single line of code. Point it to a set of classes for a low-level flow diagram when you need the details.
Brainstorming and system design - when you're whiteboarding a new service or debating trade-offs, ask it to visualize the architecture as you go. Iterate by saying "add a cache here" or "swap Kafka for SQS" instead of redrawing from scratch.
Documentation that stays alive - drop the
.excalidrawfile into your repo and update it with natural language as the system evolves. No more stale diagrams from six sprints ago.
Quick Start
Install
pip install excalidraw-architect-mcpOr run without installing (requires uv):
uvx excalidraw-architect-mcpConfigure MCP in Your IDE
Cursor - Add to .cursor/mcp.json:
{
"mcpServers": {
"excalidraw-architect": {
"command": "excalidraw-architect-mcp",
"transport": "stdio"
}
}
}Windsurf / Other IDEs - Same pattern; point to the excalidraw-architect-mcp command over stdio.
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.mdFor 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.
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"
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:
Category | Technologies |
Database | PostgreSQL, MySQL, MongoDB, DynamoDB, Cassandra, ClickHouse, SQLite, CockroachDB |
Message Queue | Kafka, RabbitMQ, SQS, Redis Streams, NATS |
Cache | Redis, Memcached, Varnish |
Load Balancer | Nginx, HAProxy, ALB/ELB, Traefik, Envoy |
Compute | Docker, Kubernetes, Lambda, ECS, Fargate |
Storage | S3, GCS, Azure Blob, MinIO |
API | REST, GraphQL, gRPC, WebSocket |
CDN | CloudFront, Cloudflare |
Monitoring | Prometheus, Grafana, Datadog, ELK |
Client | Browser, Mobile, Desktop, CLI |
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)
MCP Tools
Tool | Description |
| Create a new diagram from structured node/connection data |
| Convert Mermaid flowchart syntax to |
| Add/remove/update nodes and connections on an existing diagram |
| Read current diagram state (call before modifying) |
Contributing
See CONTRIBUTING.md for details.
License
MIT - see LICENSE.