Excalidraw AI — Local Diagram Generator

Generate rich, annotated Excalidraw diagrams from plain English — entirely on your own machine. No cloud, no API keys, no internet required after setup.

Describe a topic and the tool runs a 4-phase LLM pipeline to produce a paper-like vertical document: hierarchical tree diagrams, per-node annotations, and a full educational summary — all saved as a .excalidraw file ready to open.

One-Line Install

Linux (Ubuntu · Debian · Fedora · Arch · Void) and macOS:

curl -fsSL https://raw.githubusercontent.com/jeel00dev/exclalidraw_mcp/main/install.sh | bash

Windows (PowerShell, run as Administrator):

iwr -useb https://raw.githubusercontent.com/jeel00dev/exclalidraw_mcp/main/install.ps1 | iex

The installer handles everything automatically — no manual steps:

• Installs Docker (per-distro: apt / dnf / pacman / xbps / brew)

• Clones this repo to ~/.excalidraw-ai/

• Downloads the AI model (~1.2 GB, cached after first run)

• Pulls Docker images and starts all services

• Installs the excalidraw-ai command

Usage

After install, generate diagrams with one command:

excalidraw-ai "machine learning pipeline" --type mindmap
excalidraw-ai "TCP/IP network stack" --type architecture --out tcp_ip
excalidraw-ai "user login with OAuth2 and JWT" --type flowchart
excalidraw-ai "photosynthesis in plants" --type mindmap --out plants

Then open http://localhost:3333 in your browser, press Ctrl+O, and load the file from ~/excalidraw_diagrams/.

Service commands

excalidraw-ai start     # start all services
excalidraw-ai stop      # stop all services
excalidraw-ai status    # show container status + health
excalidraw-ai update    # pull latest code + images
excalidraw-ai help      # show all options

What Gets Generated

Each diagram is a vertical document (reads top-to-bottom like study notes):

─── Section 1: Encoder ──────────────────────────────
  [Tree diagram — root → groups → detail nodes]

  • Input Embedding: Converts token IDs to dense vectors...
  • Positional Encoding: Adds position info since attention...
  ...

─── Section 2: Decoder ──────────────────────────────
  [Tree diagram]

  • notes...

─── Educational Summary ─────────────────────────────
  The Transformer architecture introduced in "Attention is All
  You Need" (2017) replaced recurrence with self-attention...

Diagram structure:

• 2-3 sections per topic (auto-decomposed by the LLM)

• Hierarchical tree per section: root → category nodes → detail leaves

• Shape variety: rectangles (components), ovals (actors/terminals), diamonds (decisions)

• Compact notes block below each tree — 1-2 sentence explanation per node

• Educational summary — 400-500 word prose at the bottom

Variable complexity — the number of shapes scales with the topic:

• Simple topic (3-5 components) → 5-8 shapes per section

• Complex topic (many layers) → 12-16 shapes per section

Examples

Transformer Architecture

excalidraw-ai "attention is all you need encoder decoder" --type architecture

Produces two sections (Encoder, Decoder), each with a 3-level tree covering input embedding, positional encoding, multi-head attention, feed-forward networks, and normalization layers.

Machine Learning Mindmap

excalidraw-ai "machine learning supervised unsupervised reinforcement" --type mindmap

Three sections, one per paradigm, each branching into algorithms, use cases, and key concepts.

Network Stack

excalidraw-ai "TCP/IP network stack" --type architecture

Generates the full layer hierarchy: Application → Transport → Internet → Network Access, with specific protocols (HTTP, TCP, UDP, IP, Ethernet) as leaf nodes.

OAuth2 Login Flow

excalidraw-ai "user login with OAuth2 JWT session management" --type flowchart

Decision-tree flowchart with diamond nodes for validation steps, success/failure branches, and JWT issuance.

Diagram Types

How It Works

Your description
      │
      ▼
Phase 0 — Decompose   topic → 2-3 focused sub-sections    (~150 tokens)
      │
      ▼  (per section)
Phase 1 — Structure   SHAPE + ARROW lines (tree hierarchy)  (~800 tokens)
Phase 2 — Notes       1-2 sentence annotation per shape     (~600 tokens)
      │
      ▼
Phase 3 — Summary     educational prose paragraph           (~600 tokens)
      │
      ▼
Layout engine → vertical document → .excalidraw file

Each phase is a separate, focused LLM call — works reliably on small (1.5B–7B) models.

Layout engine:

• Sections stack top-to-bottom (document layout, not a spreadsheet)

• Tree layout uses subtree-width centering — children center under their parent

• Dynamic column stride scales the tree to fit the 1400px document width

• Notes appear as a bullet-list block below each section's tree

Docker Stack

The full stack runs as three Docker services:

Start / stop manually:

cd ~/.excalidraw-ai
docker compose up -d excalidraw-ui llama-server
docker compose run --rm generator "your topic" --type mindmap
docker compose down

Configuration

Edit ~/.excalidraw-ai/.env to customise:

# AI model (filename inside MODELS_DIR)
MODEL_FILE=qwen2.5-1.5b-instruct-q5_k_m.gguf

# Storage paths
MODELS_DIR=/home/you/.excalidraw-ai/models
DIAGRAMS_DIR=/home/you/excalidraw_diagrams

# Ports
EXCALIDRAW_PORT=3333
LLAMA_PORT=8080

# If you already have llama-server running elsewhere:
# LLAMA_BASE_URL=http://192.168.1.10:8080

Bring your own model

If you already have a GGUF model (e.g. DeepSeek-Coder-6.7B), copy or symlink it:

cp /path/to/your/model.gguf ~/.excalidraw-ai/models/
# Then update .env:
MODEL_FILE=your_model.gguf
docker compose restart llama-server

Recommended models:

MCP Server (Claude Desktop / Cursor)

If you use Claude Desktop or Cursor, you can generate diagrams directly from chat.

Linux — edit ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "excalidraw": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/exclalidraw_mcp", "run", "excalidraw-mcp"]
    }
  }
}

macOS — edit ~/Library/Application Support/Claude/claude_desktop_config.json (same content).

Restart Claude Desktop, then ask: "Generate a mindmap about photosynthesis"

Available MCP tools:

Manual Setup (without install.sh)

If you prefer to set up manually:

# 1. Clone
git clone https://github.com/jeel00dev/exclalidraw_mcp
cd exclalidraw_mcp

# 2. Python venv
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

# 3. Start llama-server (you provide the model)
llama-server -m /path/to/model.gguf --port 8080 -c 8192

# 4. Generate
./generate.sh "your topic" --type mindmap

generate.sh starts the Excalidraw Docker viewer automatically if Docker is available.

Project Structure

exclalidraw_mcp/
├── src/excalidraw_mcp/
│   ├── server.py       — MCP server + tool definitions
│   ├── pipeline.py     — 4-phase generation pipeline
│   ├── generator.py    — prompts, parser, tree layout, file I/O
│   ├── cli.py          — excalidraw-generate CLI entry point
│   └── llm_client.py   — llama.cpp HTTP client
├── Dockerfile          — generator container image
├── docker-compose.yml  — full stack (UI + LLM + generator)
├── install.sh          — one-liner installer (Linux/macOS)
├── install.ps1         — one-liner installer (Windows)
├── generate.sh         — standalone script (manual setup)
├── .env.example        — configuration template
└── pyproject.toml

Troubleshooting

excalidraw-ai command not found after install Run source ~/.bashrc (or open a new terminal). If it's in ~/.local/bin, add to PATH:

export PATH="$HOME/.local/bin:$PATH"

LLM server not running / health check fails

excalidraw-ai status           # check container state
docker logs excalidraw-llama   # see server output
excalidraw-ai start            # restart services

Model loading takes too long Large models (4B+) can take 30-60 seconds to load. The installer waits automatically. If you get a timeout, check docker logs excalidraw-llama — it will show loading progress.

Diagram has very few shapes (2-3) The LLM may have output an unexpected format. The pipeline retries up to 4 times automatically. Try a more specific description or a larger model.

Docker not available on install On Void Linux, Docker requires the runit service to be enabled:

sudo ln -sf /etc/sv/docker /var/service/
sudo sv start docker
sudo usermod -aG docker $USER   # then log out and back in

Then re-run install.sh.

Tool not appearing in Claude Desktop Check claude_desktop_config.json for JSON syntax errors, then fully quit and restart Claude Desktop (not just reload).

License

MIT