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 .excalidraw file 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-mcp

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

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 -

... View full README on GitHub