excalidraw-toolkit

Excalidraw Toolkit

An AI-powered diagramming toolkit for Claude Code. Say "diagram this repo" and watch your codebase turn into an architecture diagram on a live Excalidraw canvas.

> diagram this repo

I found 6 components and 5 connections:
  - Next.js Frontend → API Routes (REST)
  - API Routes → Prisma ORM → PostgreSQL (SQL)
  - API Routes → NextAuth (auth) + Stripe API (payments)

Does this look right?

> looks good

[Building diagram on live canvas...]

Install

npx excalidraw-toolkit init
npx excalidraw-toolkit start

Two commands. init copies skills to ~/.claude/plugins/ and configures the MCP server. start clones, builds, and launches the canvas server (first run), then opens your browser.

Restart Claude Code and try: "diagram this repo"

Verify setup with:

npx excalidraw-toolkit doctor

Alternative: install via Claude Code plugin marketplace

/plugin marketplace add edwingao28/excalidraw-skill
/plugin install excalidraw@excalidraw-skill

What You Get

Auto-Diagram — Zero-Config Codebase Visualization

Just say "diagram this repo". No description needed.

The auto-diagram skill runs a 6-phase pipeline:

• Detect project type (monorepo, microservices, standard app) and framework (Next.js, Django, Go, Rails, etc.)
• Discover components (frontend, API routes, database, queues, cache, auth, external services)
• Map connections between components (REST, SQL, gRPC, events, imports)
• Verify with you before drawing — presents a summary, asks for confirmation
• Choose layout (vertical flow, horizontal pipeline, hub-and-spoke, or zoned modules)
• Generate the diagram on the live canvas with color-coded components

Works with any language. Context budget prevents blowout on large codebases.

Agentic Self-Critique

Every diagram goes through an automatic quality check before you see it:

• Snapshot the canvas for rollback safety
• Geometric validation via query_elements — detects overlapping shapes, cramped spacing, broken zones
• Visual validation via screenshot — checks arrow labels, text readability, title, centering
• Auto-fix up to 2 rounds. If fixes make things worse, rolls back to the snapshot

You never see a broken diagram. The self-critique loop catches layout issues that would otherwise require manual tweaking.

Described Diagrams

When you know what you want, describe it:

"Draw a microservices architecture with: React frontend, API Gateway,
Auth Service, User Service, Order Service, RabbitMQ, PostgreSQL, Redis"

Or trace data flows:

"Trace how the auth token flows from login to API request to database query"

Or convert from Mermaid:

"Create an excalidraw diagram from this mermaid:
graph TD; A[Frontend] -->|REST| B[API]; B -->|SQL| C[Database]"

Examples

Same prompt, two renderers: Markdown (Mermaid via create_from_mermaid) vs Excalidraw (native canvas via batch_create_elements).

Microservices Architecture

Markdown	Excalidraw

CI/CD Pipeline

Markdown	Excalidraw

Event-Driven System

Markdown	Excalidraw

Data Pipeline

Markdown	Excalidraw

Architecture

The toolkit has three layers — only the first is bundled:

Layer	What	Bundled?
Skills (this package)	Markdown prompts that guide Claude's diagram generation	Yes
MCP Server (mcp-excalidraw-server)	Bridge between Claude and the Excalidraw canvas — provides batch_create_elements, get_canvas_screenshot, etc.	No — auto-downloaded via npx -y on first use
Canvas Server (mcp_excalidraw-canvas)	Live Excalidraw editor running in your browser at localhost:3000	No — auto-cloned and built on first npx excalidraw-toolkit start

How It Works

Two skills, one toolkit:

Skill	Triggers On	Does
auto-diagram	"diagram this repo", "visualize the architecture"	Analyzes codebase, discovers components, generates diagram
excalidraw	"draw a diagram of X", user provides description/sample	Renders user-specified diagrams with precise layout control

Both skills use MCP tools to draw on a live Excalidraw canvas:

Tool	Purpose
batch_create_elements	Create all shapes + arrows in one call
get_canvas_screenshot	Visual verification after each step
query_elements	Geometric validation for self-critique
snapshot_scene / restore_snapshot	Rollback safety during self-critique
export_to_image	Save as PNG or SVG
export_scene	Save as editable .excalidraw file
export_to_excalidraw_url	Generate a shareable link

Color Palette

Every component type gets a consistent color:

Component	Background	Stroke
Frontend/UI	#a5d8ff	#1971c2
Backend/API	#d0bfff	#7048e8
Database	#b2f2bb	#2f9e44
AI/ML	#e599f7	#9c36b5
Queue/Event	#fff3bf	#fab005
External API	#ffc9c9	#e03131
Storage	#ffec99	#f08c00
Cache	#ffe8cc	#fd7e14
Zone/Group	#e9ecef	#868e96

Cloud-specific palettes (AWS, Azure, GCP, Kubernetes) are included in references/colors.md.

CLI Commands

npx excalidraw-toolkit init        # install skills + configure MCP server
npx excalidraw-toolkit start       # clone + build + start canvas server + open browser
npx excalidraw-toolkit stop        # stop canvas server
npx excalidraw-toolkit update      # re-install (overwrites existing)
npx excalidraw-toolkit uninstall   # remove skills + MCP config
npx excalidraw-toolkit doctor      # check installation health
npx excalidraw-toolkit version     # print version

Compatible MCP Servers

Any Excalidraw MCP server exposing the core tools works. Register under key "excalidraw".

Package	Tools	Install
mcp-excalidraw-server (default)	26	npx -y mcp-excalidraw-server
excalidraw-mcp-server	16	npx -y excalidraw-mcp-server

Requirements

• Claude Code CLI
• Node.js >= 18
• Git (for cloning canvas server on first start)
• A browser (canvas opens automatically at http://localhost:3000)

Credits

Created by @edwingao28 with Claude Code.

License

MIT