excalidrawer

Code-first Excalidraw diagram generation — CLI, MCP server, and SVG/PNG/WebP export.

Hand-drawn Excalidraw diagrams from code, an MCP call, or a plain-language request to an agent. Every figure below is real output — a .excalidraw file you can still open and edit, plus SVG/PNG/WebP — generated by examples/gallery.mjs with no browser involved.

What it makes

Nine diagram types, each with its own agent skill. Click a figure for full size.

New in 0.6.1: pie charts and 100% stacked bars in the chart skill.

New in 0.6.0: state machines, pyramids and funnels, bar and line charts, and a left-to-right data-stack overview as a fourth architecture layout — plus WebP output.

Why not just use Excalidraw directly?

Excalidraw is a fantastic drawing tool — you open a canvas and arrange boxes by hand. excalidrawer is a generation tool: it turns code (or a structured spec, or an agent's intent) into the same hand-drawn-style diagrams, with no browser and no manual dragging.

Use Excalidraw when a human is sketching once. Reach for excalidrawer when the diagram needs to come out of an automated pipeline:

• In code / scripts — build diagrams from data, keep them in version control, and regenerate deterministically (fixed seed → clean diffs) instead of re-dragging boxes every time the source changes.
• In CI / docs builds — render .svg / .png as a build step so the diagrams in your README or docs site never drift from the system they describe.
• In an AI agent — the MCP server (and the agent plugin's skills) let an agent produce a diagram in-context ("draw the auth flow") without leaving the conversation.

It produces real .excalidraw files, so the output is still fully editable in Excalidraw afterward — generate the first draft programmatically, hand-tweak if you want.

Install

Most users want the agent plugin — it bundles the flowchart / timeline / architecture / sequence / comparison / tree skills and wires them to the MCP server, so you can just say "draw the auth flow" inside Claude Code or Codex. The CLI and library entry points are below for scripting and custom use cases.

Agent plugin (Claude Code / Codex, recommended)

Two commands and you're done — the plugin bundles the skills and auto-registers the MCP server via its manifest (no global npm install, no separate claude mcp add / codex mcp add).

In Claude Code:

/plugin marketplace add guohaonan-shy/excalidrawer
/plugin install excalidrawer@excalidrawer-dev

In Codex:

codex plugin marketplace add guohaonan-shy/excalidrawer
codex plugin add excalidrawer@excalidrawer-dev

Codex reads this repo's .claude-plugin/marketplace.json directly, so both clients get the same skills and the same auto-registered MCP server — verify with codex plugin list / codex mcp list.

The MCP server runs via npx, so the first invocation downloads the package into the npx cache (~5-10 s); subsequent runs use the cache.

Auto-registering the MCP server from the plugin manifest is a plugin-host feature. In a client that doesn't install plugins, register the MCP server directly — see MCP Server below.

CLI & MCP server only

If you only want the binaries (e.g. to script excalidrawer render in a build):

npm install -g excalidrawer

This puts two commands on your PATH:

• excalidrawer — the CLI (render, compute-layout)
• excalidrawer-mcp — the MCP server that MCP clients launch

Library

Only needed for the programmatic API (see Custom Scripts):

npm install excalidrawer

MCP Server

excalidrawer-mcp is a stdio MCP server exposing two tools:

Tool	What it does
render_diagram	Render an array of sugar shorthand or raw Excalidraw elements to .excalidraw / .svg / .png / .webp files.
compute_layout	Compute coordinates from a layout helper (grid, chain, swimlane, hub-and-spoke, edge anchors, U-routing, label anchors, titled boxes, row equalization).

Each command below registers the server with npx -y -p excalidrawer@latest -c excalidrawer-mcp — no global install needed, and always the latest published version.

Claude Code

claude mcp add excalidrawer -- npx -y -p excalidrawer@latest -c excalidrawer-mcp

Verify with claude mcp list — it should report ✓ Connected.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows), then restart the app:

{
  "mcpServers": {
    "excalidrawer": {
      "command": "npx",
      "args": ["-y", "-p", "excalidrawer@latest", "-c", "excalidrawer-mcp"]
    }
  }
}

Codex

Only if you want the two MCP tools without the skills. The recommended Codex path is the plugin, which brings the skills and this MCP server together — a bare codex mcp add gives you render_diagram / compute_layout but none of the skills' guidance (palette conventions, back-edge routing, layout components, quality gates).

codex mcp add excalidrawer -- npx -y -p excalidrawer@latest -c excalidrawer-mcp

Agent Skills

The skills/ directory holds two layers: one entry skill per diagram type (the one you invoke), and a step skill steps they call when they reach a step. They ship as part of the agent plugin above — Claude Code and Codex both install them.

This is the beginning of the README. Read the rest at the original. Read the full README ↗