excalidraw-mcp

Generate 20+ types of beautiful hand-drawn diagrams with AI — flowcharts, sequence, architecture, mind maps, ER, class, state, timeline, pie charts, kanban, wireframes, and more — with Sugiyama hierarchical layout, CJK support, and zero learning curve.

By Maaker.AI

Install

Claude Code (recommended)

claude mcp add excalidraw -- uvx maaker-excalidraw-mcp

Claude Desktop

Add to your MCP config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "excalidraw": {
      "command": "uvx",
      "args": ["maaker-excalidraw-mcp"]
    }
  }
}

pip

pip install maaker-excalidraw-mcp

Tools

Quick Examples

Flowchart

Just tell your AI assistant:

"Create a flowchart: User Request → Load Balancer → API Server → Database"

The AI will call create_flowchart with structured data, and you'll get a .excalidraw file with:

• Sugiyama hierarchical layout — proper handling of branches, merges, cycles, and disconnected subgraphs
• Auto-calculated box sizes based on text content
• Perfectly centered text (including Chinese/CJK characters)
• Smart arrow routing with proper edge binding
• Hand-drawn style that looks great in docs and presentations
• 4 directions: LR (left-to-right), RL, TB (top-to-bottom), BT

Architecture Diagram

"Create an architecture diagram with Frontend (React, Next.js), Backend (API Server, Auth Service), and Database (PostgreSQL, Redis) layers"

Generates a layered diagram with components organized by tier, automatic sizing, and connections between layers.

Read & Modify

"Read the diagram at ./my-system.excalidraw and add a 'Cache' node connected to the API Server"

Works with existing .excalidraw files — read their structure, add/remove nodes, add connections.

Why excalidraw-mcp?

vs Official Excalidraw MCP (excalidraw/excalidraw-mcp)

vs Mermaid-based tools

• Free layout: Not constrained by Mermaid syntax limitations
• Hand-drawn style: Native Excalidraw look, not rendered code blocks
• Editable output: Drag the .excalidraw file to excalidraw.com to continue editing

Tool Reference

create_flowchart

Input:
  nodes: [{label: "Step 1", color?: "blue", shape?: "rectangle"}]
  edges: [{from: "Step 1", to: "Step 2", label?: "next"}]
  direction?: "LR" | "RL" | "TB" | "BT"  (default: "LR")
  title?: "My Flowchart"
  output_path?: "/path/to/output.excalidraw"

Output: Path to generated .excalidraw file

Colors: blue, green, purple, yellow, red, gray, orange, pink

Shapes: rectangle (default), diamond (decisions), ellipse (start/end)

create_architecture_diagram

Input:
  layers: [{
    name: "Frontend",
    color?: "blue",
    components: [{label: "React"}, {label: "Next.js"}]
  }]
  connections?: [{from: "React", to: "API Server"}]
  output_path?: "/path/to/output.excalidraw"

Output: Path to generated .excalidraw file

modify_diagram

Input:
  file_path: "/path/to/existing.excalidraw"
  add_nodes?: [{label: "New Node", color?: "green", x?: 100, y?: 100}]
  remove_labels?: ["Old Node"]
  add_connections?: [{from: "A", to: "B"}]
  output_path?: "/path/to/output.excalidraw"

Output: Path to modified file

read_diagram

Input:
  file_path: "/path/to/diagram.excalidraw"

Output: Structured description (shapes, connections, colors)

export_diagram

Input:
  file_path: "/path/to/diagram.excalidraw"
  format: "svg"

Output: Path to exported SVG file

Technical Details

Sugiyama Hierarchical Layout

Uses the grandalf library for proper directed graph layout:

• Layer assignment: Nodes placed in layers based on graph topology
• Crossing minimization: Multi-pass optimization to reduce edge crossings
• Coordinate assignment: Balanced positioning within layers
• Cycle handling: Feedback edge detection for cyclic graphs
• Disconnected subgraphs: Automatic side-by-side placement

CJK Width Estimation

Accurate text width calculation for mixed Chinese/English text:

Arrow Binding

Uses Excalidraw's modern fixedPoint + orbit binding (not the deprecated focus/gap format):

{
  "startBinding": {
    "elementId": "box1",
    "fixedPoint": [1.0, 0.5001],
    "mode": "orbit"
  }
}

Arrows automatically connect at the correct edge based on relative positions.

Development

git clone https://github.com/maaker-ai/excalidraw-mcp.git
cd excalidraw-mcp
uv sync --dev
uv run pytest

License

MIT