Excalidraw MCP Server, CLI & Agent Skill

mcp-excalidraw-server gives AI agents a live Excalidraw canvas they can draw on, look at, refine, and save into your repo. Your agent creates architecture diagrams and flowcharts programmatically, sees its own work via screenshots, fixes layout problems, and exports .excalidraw files you can commit next to your code.

One canvas, three ways to drive it:

Agent Skill + CLI — recommended for coding agents (Claude Code, Codex CLI, Cursor, OpenCode): npx -y mcp-excalidraw-server <command>. Zero config, auto-starts the canvas, composable JSON in/out.
MCP Server — 26 tools over stdio for any Model Context Protocol client (Claude Desktop, Cursor, Codex CLI, Antigravity, ...). Speaks MCP 2026-07-28 (server/discover, per-request _meta envelope, tool calls without a handshake) and stays compatible with 2025-era clients that open with initialize.
REST API — plain HTTP for LangChain and custom frameworks.

Core drawing runs locally (Node ≥ 20, MIT licensed) — no API keys or accounts. Mermaid conversion runs in the local browser canvas; share is optional and uploads an encrypted scene to excalidraw.com. The canvas page loads Excalidraw's fonts from the esm.sh CDN.

Demo

AI agent creates a complete architecture diagram from a single prompt (4x speed). Watch full video on YouTube

What It Is

Ask your agent to "draw the architecture of this service" and it produces a real, editable Excalidraw diagram — not a one-shot image. Because the agent can query, screenshot, and update individual elements, it iterates until labels fit, nothing overlaps, and arrows route cleanly; then it exports the result as a .excalidraw file that lives in your repo and gets updated when the code changes.

Under the hood there are two processes, one product:

Canvas server: Excalidraw web UI + REST API + WebSocket real-time sync (default http://127.0.0.1:3000)
A thin front-end of your choice: the CLI, the MCP stdio server, or raw HTTP — all drive the same canvas

Since v1.1 the canvas server starts itself: canvas-driving CLI commands (and the MCP server on launch) auto-spawn it if nothing is listening. status only inspects the current server state. Set EXCALIDRAW_NO_AUTOSTART=1 to opt out.

How We Differ from the Official Excalidraw MCP

Excalidraw has an official MCP — a chat widget that streams a diagram inline from a single prompt (the model gets two tools: a format reference and create_view). It's great for "draw me a cat" in Claude or ChatGPT. We solve a different problem: giving coding agents a persistent canvas workbench.

	Official Excalidraw MCP	This Project
Approach	Prompt in, diagram out (one-shot widget)	Programmatic element-level control (CLI + 26 MCP tools)
State	Checkpoints inside the chat widget	Persistent live canvas with real-time sync
Element CRUD	Declarative re-send with delete markers	Full create / read / update / delete per element
AI sees the canvas	No	`describe` (structured text) + `screenshot` (image)
Iterative refinement	Regenerate from checkpoint	Draw → look → adjust → look again, element by element
Layout tools	No	align, distribute, group / ungroup, lock, duplicate
File I/O	No model-facing export	`.excalidraw` export/import — diagrams as repo artifacts
Snapshot & rollback	Widget-side checkpoints	Named server-side snapshots
Mermaid conversion	No	`mermaid` / `create_from_mermaid`
Shareable URLs	Widget-only	`share` / `export_to_excalidraw_url`
Viewport control	Camera animations	`set_viewport` (zoom-to-fit all or selected elements, center on one element, manual zoom)
Works without MCP	No	Yes — CLI + agent skill + REST API
Multi-agent	Single chat	Multiple agents on the same canvas concurrently

TL;DR — The official MCP shows Excalidraw diagrams in your chat. This project gives your coding agent a full Excalidraw workbench: a canvas it can draw on, inspect, refine, and commit to your repo.

What's New

Current package version: 2.1.2. The current release line is v2.1 — Headless Rendering.

v2.1.2 — Fixes

Snapshot restore no longer wipes the canvas; frames restore and import. (#101, thanks @sanjayy0612; #120)
One label per shape, even across updates and renames. (#121, thanks @sdrshn-nmbr)
Dropped images survive reload and show up in exports. (#122, thanks @appdesigngeeks)
Text is no longer clipped when the font loads late. (#123, #124)

v2.1.1 — Fixes

Large exports no longer fail with invalid order key. (#115, thanks @fernandovmacedo)
Text and arrows no longer drift on each canvas sync. (#116, thanks @hidinginabunker)
Library installs work and persist; labels re-wrap on resize. (#113, thanks @lukemariano)

v2.1 — Headless Rendering

Screenshots and image exports no longer need a browser tab. screenshot, export_to_image and get_canvas_screenshot render inside the canvas server: Excalidraw's own SVG exporter runs under Node (jsdom) and resvg rasterizes to PNG with bundled Excalifont/Virgil/Cascadia/Liberation fonts. Same output as the tab, deterministic (byte-identical for an unchanged scene), a few milliseconds per render, works in CI and Docker. See Headless Rendering.
New render options on the CLI, REST and MCP: dark, scale (1–4), padding, elementIds (render a subset), frameId (render one frame), embedFonts. --renderer browser keeps the old tab path.
New render command: npx -y mcp-excalidraw-server render docs/arch.excalidraw --out docs/arch.png renders a committed file offline — no canvas server at all.
Shapes created without width/height now default to 100×100 in exports and renders (matching the canvas) instead of collapsing to 0×0.
Text stored with width: 0, height: 0 (scenes from pre-2.0 servers) is re-measured on export instead of exporting invisible. (#107)

v2.0 — Interchange-Grade Exports & MCP 2026-07-28

Breaking: Node >= 20 required (was 18) — the MCP TypeScript SDK v2 sets the floor. Everything else is backward compatible, including existing MCP client configs.
MCP protocol revision 2026-07-28: modern clients can call tools statelessly without an initialization handshake (server/discover, per-request _meta envelopes); legacy initialization-based clients keep working unchanged. (#98, thanks @anxkhn)
Exports render everywhere now: .excalidraw / .excalidraw.md files contain real Excalidraw elements — shape and arrow labels as bound text, live arrow bindings — so they open correctly on excalidraw.com and in the Obsidian Excalidraw plugin instead of losing labels (or being re-saved empty by the plugin). (#93, #95)
Byte-stable exports: deterministic ids, seeds, and key order — re-exporting an unchanged scene is byte-identical, so committed diagrams and vault files never produce phantom git diffs, and Obsidian block references survive re-exports.
Obsidian vault fixes: Windows/CRLF .excalidraw.md files import correctly (#94, thanks @cason-miles); ## Text Elements block references now cover shape labels too.
Element fields are never silently dropped: unknown Excalidraw properties (containerId, textAlign, originalText, ...) pass through the server intact — fixes browser-edited text vanishing after sync. (#92, thanks @junuxyz)
Mermaid conversion merges into the existing canvas instead of replacing it, and each browser tab holds exactly one WebSocket connection (no more doubled labels). (#91)
Viewport control: set_viewport gains scrollToElementIds (multi-element zoom-to-fit) and viewportZoomFactor, with strict single-mode validation and real error reporting. (#86, thanks @acercyc)
Dark mode: the canvas page chrome follows the editor theme and persists it across reloads. (#89, thanks @danielsvane)

v1.1 — CLI-First

First-class CLI: every capability is now a composable command — npx -y mcp-excalidraw-server add|query|describe|screenshot|export|import|mermaid|snapshot|arrange|share|... — JSON on stdout, meaningful exit codes. Also installed as the excalidraw-canvas alias.
Zero-setup: canvas-driving CLI commands and the MCP server auto-start the canvas server if it isn't running (closes #66). Opt out with EXCALIDRAW_NO_AUTOSTART=1.
apply: multi-op patches ({"create":[...],"update":[{"id":"a","set":{...}}],"delete":[...]}) in a single invocation.
install-skill: npx -y mcp-excalidraw-server install-skill --dir <skills-root> copies the portable agent skill into the directory your agent chooses (project or global), cleanly replacing older versions.
Skill is now CLI-first and no longer needs a cloned repo or configured MCP server to work.
Typed queries: query --filter locked=true --filter label.text=API — booleans, numbers, and nested keys work.
Internals: shared core library (src/core/) behind both the CLI and MCP server; canvas groupIds are the source of truth for grouping (ungroup now works across restarts); node-fetch dropped; MCP version metadata derived from package.json; canvas server writes a pidfile and shuts down cleanly.

Installation

The only prerequisite is Node.js ≥ 20.

Easiest: let your agent install it

Copy this into your coding agent — it installs the portable skill into the project/global skill directory that agent already knows how to use, then verifies it by drawing a test diagram:

Install the Excalidraw canvas toolkit so you can draw diagrams for me:

1. Choose the right skill directory for this agent and scope (project or global).
2. Run: npx -y mcp-excalidraw-server install-skill --dir <that-skills-directory>
3. Read the installed excalidraw-skill/SKILL.md so you know the drawing workflow.
4. Start the canvas with: npx -y mcp-excalidraw-server start
   then tell me I can open http://127.0.0.1:3000 to watch you draw (optional).
5. Draw a small test diagram — two labeled boxes connected by an arrow — take a
   screenshot, and show me the result to confirm everything works.

Manual install

You are...	Install with	Then
Modern coding agent	`npx -y mcp-excalidraw-server install-skill --dir <skills-root>`	Let the agent choose project/global scope and its skill root
Claude Code shortcut	`npx -y mcp-excalidraw-server install-skill`	Installs to `~/.claude/skills` for backward compatibility
Codex shortcut	`npx -y mcp-excalidraw-server install-skill --target codex`	Installs to `~/.codex/skills` for backward compatibility
MCP client user (Claude Desktop, Cursor, ...)	Add the npx config below	See Configure MCP Clients
CLI user / scripting	Nothing — `npx -y mcp-excalidraw-server <command>`	See CLI Reference
Contributor / from source	`git clone` + `npm ci` + `npm run build`	See Quick Start (From Source / Docker)

There is no separate server setup: any drawing command auto-starts the local canvas server on http://127.0.0.1:3000.

60-Second Quick Start (CLI)

No clone, no config:

# start the canvas (drawing commands auto-start it too) and open it
npx -y mcp-excalidraw-server start
open http://127.0.0.1:3000   # optional: watch live (only mermaid needs the tab)

# draw something
echo '[
  {"id":"api","type":"rectangle","x":100,"y":100,"width":160,"height":80,"text":"API Server","backgroundColor":"#a5d8ff"},
  {"id":"db","type":"rectangle","x":400,"y":100,"width":160,"height":80,"text":"Database","backgroundColor":"#99e9f2"},
  {"type":"arrow","x":0,"y":0,"startElementId":"api","endElementId":"db","text":"SQL"}
]' | npx -y mcp-excalidraw-server add

# let your agent see its work
npx -y mcp-excalidraw-server describe
npx -y mcp-excalidraw-server screenshot --out diagram.png

# diagrams as repo artifacts
mkdir -p docs
npx -y mcp-excalidraw-server export --out docs/architecture.excalidraw

# or straight into an Obsidian vault (.md extension → Obsidian Excalidraw plugin format)
npx -y mcp-excalidraw-server export --out ~/vault/diagrams/architecture.excalidraw.md

Give your agent the full playbook:

npx -y mcp-excalidraw-server install-skill --dir <skills-root>
npx -y mcp-excalidraw-server install-skill --print-source  # inspect bundled source path

Security note: The canvas server binds 127.0.0.1 only by default. If you expose it on a network interface (HOST=0.0.0.0), put network-level access controls in front — the API has no built-in authentication.

Agent Skill

The skill at skills/excalidraw-skill/ teaches agents the full workflow — layout planning, the screenshot-verify-fix quality loop, arrow routing, anti-patterns, snapshots, and file I/O. It works through the CLI (preferred, zero setup), MCP tools (if configured), or raw REST — in that order.

npx -y mcp-excalidraw-server install-skill --dir <skills-root>

The command copies the bundled excalidraw-skill/ directory into <skills-root>/excalidraw-skill. Let your agent choose whether that root should be project-level or global. Re-running install-skill upgrades in place — it replaces the target directory, so files removed upstream don't linger.

Where the skill shines:

Diagrams as code artifacts: export .excalidraw files into the repo, commit them, re-import + refine when the architecture changes.
Obsidian vaults: export with a .excalidraw.md extension and the file opens natively in the Obsidian Excalidraw plugin — no compatibility-mode warning, block references and sync work; import reads both plain and lz-string-compressed vault files back.
Self-verifying diagrams: the agent screenshots its own work and fixes truncation/overlap before calling it done.
No-MCP environments: CI jobs, plain shells, and frameworks get the same capabilities through the CLI.

CLI Reference

npx -y mcp-excalidraw-server <command> or (after npm i -g mcp-excalidraw-server) excalidraw-canvas <command>.

Conventions: JSON results on stdout — except describe (plain text by design) and raw-content output when --out is omitted (export prints the scene JSON, screenshot --format svg prints SVG). Diagnostics on stderr. Exit codes: 0 ok, 1 error, 2 usage, 3 canvas unreachable, 4 browser tab required (only mermaid and screenshot --renderer browser). Canvas URL from EXPRESS_SERVER_URL or --url. Canvas-driving commands auto-start the server; status only reports current state. Explicit start overrides the EXCALIDRAW_NO_AUTOSTART=1 opt-out (it's user intent, not auto-start).

Command	Description
`start` / `stop` / `status`	Manage the canvas server (detached; `stop` identity-checks the live server via `/health` before signaling)
`add [file\|-]`	Batch-create elements from a JSON array (file or stdin); `--one '{...}'` for a single element
`apply [file\|-]`	One-call multi-op patch: `{"create":[...],"update":[{"id":"a","set":{...}}],"delete":["id"]}`
`get <id>` / `delete <id...>`	Read / remove elements
`update <id> --set '{...}'`	Update an element
`query`	`--type`, `--bbox x0,y0,x1,y1`, `--filter k=v` (typed, nested keys), `--filter-json '{...}'`
`describe`	AI-readable scene summary (plain text)
`screenshot`	Render the canvas headless (no browser tab): `--out f.png\|f.svg`, `--format png\|svg`, `--scale 1-4`, `--dark`, `--padding N`, `--no-background`, `--ids a,b`, `--frame <id>`, `--no-embed-fonts`; `--renderer browser` uses an open tab instead
`render [file\|-]`	Render a `.excalidraw` / `.excalidraw.md` file to PNG/SVG offline — no canvas server, same flags as `screenshot`
`export [--out f.excalidraw] [--format json\|obsidian]` / `import [file\|-] [--replace]`	Scene file I/O — a `.md` out path writes Obsidian's `.excalidraw.md` format; `import` reads it back
`mermaid [file\|-]`	Mermaid → canvas (browser tab required)
`snapshot save\|list\|restore <name>`	Named snapshots
`arrange align\|distribute\|group\|ungroup\|lock\|unlock\|duplicate`	Layout ops (`--ids a,b,c`, `--to left\|horizontal\|...`)
`share`	Encrypted upload → shareable excalidraw.com URL
`clear --yes`	Wipe the canvas
`install-skill [--dir <skills-root>]`	Install the portable agent skill

Labels and arrow bindings use the agent-friendly format everywhere in the CLI: "text" on any shape, "startElementId"/"endElementId" on arrows — normalization is automatic. For a native frame, add a "type":"frame" element with a "name" and set "frameId" on its children.

Headless Rendering

Since v2.1, screenshot, export_to_image and get_canvas_screenshot render without a browser. Inside the canvas server, the scene is prepared with the canvas tab's own code (label sizing, wrapping and centering, defaults) and Excalidraw's own exportToSvg draws it under Node (a small jsdom shim supplies the DOM it expects, and text is measured with the bundled fonts' real glyph widths); resvg rasterizes the SVG to PNG. The output is what the Excalidraw canvas draws — same SVG structure as a browser export, text within half a pixel — and it is deterministic: an unchanged scene renders to byte-identical SVG and PNG, so committed images stay diff-clean.

Fonts: Excalifont, Virgil, Cascadia Code and Liberation Sans ship as TTFs in assets/fonts (all SIL OFL 1.1; see assets/fonts/LICENSES.md). SVGs embed the faces they use, so they look right in browsers, GitHub and editors. Nunito, Lilita One and Comic Shanns render with the closest bundled face for now. Text in other scripts (CJK, emoji) falls back to the machine's fonts, with a warning.
Options (CLI flags / REST body / MCP params): background, dark, scale 1–4 (PNG), padding, elementIds or frameId to render a subset, embedFonts. EXCALIDRAW_RENDER_MAX_DIM (default 8192) caps the PNG's largest side.
--renderer browser asks an open canvas tab to render instead (the pre-2.1 path). Useful for a second opinion; it is slower and the tab's unsynced edits are discarded first.
Offline: render docs/arch.excalidraw --out docs/arch.png needs no canvas server at all — a natural fit for CI jobs that keep images next to committed diagrams.
Still browser-bound: Mermaid conversion (mermaid, create_from_mermaid) and set_viewport.

The renderer bundle is built by npm run build:server (dist/render/excalidraw-node.mjs); npm run test:render exercises it without a browser.

Configure MCP Clients

The MCP server runs over stdio. Since v1.1 the simplest config is npx — no clone, no absolute paths, and the canvas auto-starts:

Environment Variables

Variable	Description	Default
`EXPRESS_SERVER_URL`	URL of the canvas server	`http://127.0.0.1:3000`
`ENABLE_CANVAS_SYNC`	Enable real-time canvas sync	`true`
`EXCALIDRAW_NO_AUTOSTART`	Set `1` to disable canvas auto-start	(unset)
`EXCALIDRAW_EXPORT_DIR`	Base directory MCP file exports may write to	current working dir
`EXCALIDRAW_RENDER_MAX_DIM`	Largest side of a headless PNG, in pixels	`8192`
`PORT` / `HOST`	Canvas server bind address	`3000` / `127.0.0.1`
`LOG_LEVEL`	Log verbosity (`error`, `warn`, `info`, `debug`)	`info`
`LOG_FILE_PATH`	Log file location	`~/Library/Logs/excalidraw-mcp.log` (macOS), `$XDG_STATE_HOME/excalidraw-mcp/excalidraw.log` (Linux), `%LOCALAPPDATA%\Excalidraw-MCP\excalidraw.log` (Windows)

Claude Desktop

Config location:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

npx (recommended)

{
  "mcpServers": {
    "excalidraw": {
      "command": "npx",
      "args": ["-y", "mcp-excalidraw-server"]
    }
  }
}

Local (node)

{
  "mcpServers": {
    "excalidraw": {
      "command": "node",
      "args": ["/absolute/path/to/mcp_excalidraw/dist/index.js"],
      "env": {
        "EXPRESS_SERVER_URL": "http://127.0.0.1:3000",
        "ENABLE_CANVAS_SYNC": "true"
      }
    }
  }
}

Docker

{
  "mcpServers": {
    "excalidraw": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "EXPRESS_SERVER_URL=http://host.docker.internal:3000",
        "-e", "ENABLE_CANVAS_SYNC=true",
        "ghcr.io/yctimlin/mcp_excalidraw:latest"
      ]
    }
  }
}

Claude Code

npx (recommended)

claude mcp add excalidraw --scope user -- npx -y mcp-excalidraw-server

Tip: for coding agents, the skill + CLI often beats MCP config entirely — let the agent pick its skill root, then run npx -y mcp-excalidraw-server install-skill --dir <skills-root>.

Local (node) - User-level (available across all projects):

claude mcp add excalidraw --scope user \
  -e EXPRESS_SERVER_URL=http://127.0.0.1:3000 \
  -e ENABLE_CANVAS_SYNC=true \
  -- node /absolute/path/to/mcp_excalidraw/dist/index.js

Docker

claude mcp add excalidraw --scope user \
  -- docker run -i --rm \
  -e EXPRESS_SERVER_URL=http://host.docker.internal:3000 \
  -e ENABLE_CANVAS_SYNC=true \
  ghcr.io/yctimlin/mcp_excalidraw:latest

Manage servers:

claude mcp list              # List configured servers
claude mcp remove excalidraw # Remove a server

Cursor

Config location: .cursor/mcp.json in your project root (or ~/.cursor/mcp.json for global config)

npx (recommended)

{
  "mcpServers": {
    "excalidraw": {
      "command": "npx",
      "args": ["-y", "mcp-excalidraw-server"]
    }
  }
}

Docker

{
  "mcpServers": {
    "excalidraw": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "EXPRESS_SERVER_URL=http://host.docker.internal:3000",
        "-e", "ENABLE_CANVAS_SYNC=true",
        "ghcr.io/yctimlin/mcp_excalidraw:latest"
      ]
    }
  }
}

Codex CLI

npx (recommended)

codex mcp add excalidraw -- npx -y mcp-excalidraw-server

Docker

codex mcp add excalidraw \
  -- docker run -i --rm \
  -e EXPRESS_SERVER_URL=http://host.docker.internal:3000 \
  -e ENABLE_CANVAS_SYNC=true \
  ghcr.io/yctimlin/mcp_excalidraw:latest

Manage servers:

codex mcp list              # List configured servers
codex mcp remove excalidraw # Remove a server

OpenCode

Config location: ~/.config/opencode/opencode.json or project-level opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "excalidraw": {
      "type": "local",
      "command": ["npx", "-y", "mcp-excalidraw-server"],
      "enabled": true
    }
  }
}

Antigravity (Google)

Config location: ~/.gemini/antigravity/mcp_config.json

{
  "mcpServers": {
    "excalidraw": {
      "command": "npx",
      "args": ["-y", "mcp-excalidraw-server"]
    }
  }
}

Notes

Docker networking: Use host.docker.internal to reach the canvas server running on your host machine. On Linux, you may need --add-host=host.docker.internal:host-gateway or use 172.17.0.1. The Docker MCP image sets EXCALIDRAW_NO_AUTOSTART=1 (it has no frontend build) — run the canvas as its own container.
In-memory storage: The canvas server stores elements in memory. Restarting the server clears all elements — use export / snapshot for persistence.

MCP Tools (26 Total)

Category	Tools
Element CRUD	`create_element`, `get_element`, `update_element`, `delete_element`, `query_elements`, `batch_create_elements`, `duplicate_elements`
Layout	`align_elements`, `distribute_elements`, `group_elements`, `ungroup_elements`, `lock_elements`, `unlock_elements`
Scene Awareness	`describe_scene`, `get_canvas_screenshot`
File I/O	`export_scene`, `import_scene`, `export_to_image`, `export_to_excalidraw_url`, `create_from_mermaid`
State Management	`clear_canvas`, `snapshot_scene`, `restore_snapshot`
Viewport	`set_viewport`
Design Guide	`read_diagram_guide`
Resources	`get_resource`

Full schemas are discoverable via tools/list or in skills/excalidraw-skill/references/cheatsheet.md.

Viewport group focus can tune framing with viewportZoomFactor:

{
  "scrollToElementIds": ["id1", "id2", "id3"],
  "viewportZoomFactor": 0.85
}

scrollToElementIds zooms to fit every requested element, while scrollToElementId centers one element without changing the current zoom. Specify only one viewport mode per request. viewportZoomFactor accepts values greater than 0 and at most 1.

Quick Start (From Source / Docker)

From source (Node >= 20):

npm ci
npm run build
PORT=3000 npm run canvas          # canvas server (terminal 1)
node dist/index.js                # MCP server over stdio (terminal 2, usually launched by your MCP client)
node dist/bin.js status           # or drive the CLI straight from the build

Docker canvas server:

docker run -d -p 3000:3000 --name mcp-excalidraw-canvas ghcr.io/yctimlin/mcp_excalidraw-canvas:latest

MCP server image: ghcr.io/yctimlin/mcp_excalidraw:latest (stdio; point EXPRESS_SERVER_URL at the canvas container).

Testing

CLI Smoke Test

npx -y mcp-excalidraw-server start
npx -y mcp-excalidraw-server status
npx -y mcp-excalidraw-server add --one '{"type":"rectangle","x":100,"y":100,"width":300,"height":200}'
npx -y mcp-excalidraw-server describe

Canvas Smoke Test (HTTP)

curl http://127.0.0.1:3000/health

Regression Checks

npm test builds the server and runs four suites, each also available on its own:

npm test
npm run test:mcp      # MCP stdio wire protocol (see below)
npm run test:bind     # default loopback bind, duplicate-start refusal
npm run test:render   # headless renderer, export order keys, scene-prep stability
npm run test:state    # atomic import and snapshot restore, sync validation

Canvas Browser Regression Tests

These Chromium tests build the app and start an isolated localhost server. They cover frame reload/reconnect, mixed scenes, failed-load sync protection, stale responses, clearing/deletion, Mermaid imports, SVG export, dropped images, and text measurement after fonts load. They refuse to reuse an existing server; set CANVAS_TEST_PORT if port 51910 is occupied.

npx playwright install chromium
npm run type-check:frontend
npm run test:canvas

MCP Stdio Wire Test

Drives dist/index.js with raw JSON-RPC frames and checks both protocol eras: server/discover, tool calls sent without any handshake, refusal of unsupported protocol revisions and malformed _meta envelopes, and the legacy initialize path.

npm run test:mcp

MCP Smoke Test (MCP Inspector)

List tools:

npx @modelcontextprotocol/inspector --cli \
  -e EXPRESS_SERVER_URL=http://127.0.0.1:3000 \
  -e ENABLE_CANVAS_SYNC=true -- \
  node dist/index.js --method tools/list

Create a rectangle:

npx @modelcontextprotocol/inspector --cli \
  -e EXPRESS_SERVER_URL=http://127.0.0.1:3000 \
  -e ENABLE_CANVAS_SYNC=true -- \
  node dist/index.js --method tools/call --tool-name create_element \
  --tool-arg type=rectangle --tool-arg x=100 --tool-arg y=100 \
  --tool-arg width=300 --tool-arg height=200

Frontend Screenshots (agent-browser)

If you use agent-browser for UI checks:

agent-browser install
agent-browser open http://127.0.0.1:3000
agent-browser wait --load networkidle
agent-browser screenshot /tmp/canvas.png

FAQ

How is this different from the official Excalidraw MCP?

The official Excalidraw MCP is a chat widget: you prompt, it streams a diagram into the conversation (the model gets two tools). This project is a workbench for coding agents: a persistent local canvas with element-level create/read/update/delete, layout tools, screenshots the model can see, snapshots, and .excalidraw file I/O — driveable via CLI, MCP, or REST. See the full comparison table.

Which AI tools does it work with?

Claude Code, Claude Desktop, Cursor, Codex CLI, OpenCode, and Google Antigravity are documented below — but any agent that can run shell commands can use the CLI, any MCP client can use the MCP server, and anything else (LangChain, custom apps) can use the REST API.

Can the AI actually see the diagram it drew?

Yes — that's the core feature. describe returns a structured text summary (ids, positions, labels, connections) and screenshot returns a rendered PNG. Agents use both to catch truncated labels, overlaps, and bad arrow routing, then fix them element by element.

Do I need a browser open?

No. Screenshots and PNG/SVG exports render headless inside the canvas server (see Headless Rendering), and everything else — creating, querying, updating elements, .excalidraw files — never needed one. Only two things still need an open tab: Mermaid conversion (it lays out in the browser) and viewport control (it moves a camera). The CLI exits with code 4 and tells you when that is the case. Opening the URL is still the way for a human to watch the agent draw.

Are my diagrams persistent?

The canvas is in-memory by design (restart = blank canvas). Persist by exporting .excalidraw files into your repo (export --out docs/architecture.excalidraw) or with named snapshots while working. Re-import a file to keep refining it later.

Are excalidraw.com share links private?

share encrypts the scene locally with AES-GCM before uploading; the decryption key is only in the URL fragment, which excalidraw.com's server never sees. Anyone you give the full link to can view the diagram.

Does it need an API key or cloud service?

No API key is required. Core drawing runs locally under MIT license. Outbound traffic is limited to the canvas page loading Excalidraw's fonts from the esm.sh CDN and the optional share upload to excalidraw.com. The CLI, MCP server and headless renderer make no other network calls.

Can I use it without configuring MCP?

Yes — that's the recommended path for coding agents: npx -y mcp-excalidraw-server install-skill --dir <skills-root> and the agent drives everything through the CLI. MCP configuration is only needed for chat clients like Claude Desktop.

Troubleshooting

CLI exit code 3 (canvas unreachable): the server is not running for an inspecting command such as status, auto-start is disabled (EXCALIDRAW_NO_AUTOSTART=1), or EXPRESS_SERVER_URL points at a non-loopback host. Run start explicitly or fix the env.
CLI exit code 4 (browser required): only mermaid and screenshot --renderer browser need an open tab — open http://127.0.0.1:3000 in a browser and retry, or drop --renderer browser to render headless.
Headless PNG shows boxes instead of CJK/emoji text: the bundled fonts cover Latin scripts; for other scripts resvg falls back to the machine's fonts (a warning is printed). Install a CJK font on the machine running the canvas server.
Canvas not updating: confirm EXPRESS_SERVER_URL points at the running canvas server (status shows the URL in use).
Canvas page shows plain fonts offline: the page loads Excalidraw's hand-drawn fonts from the esm.sh CDN, so without internet access it falls back to system fonts. Headless screenshots and render use the bundled fonts and are unaffected.
Something else looks wrong: the server log has the details; its location is in Environment Variables (LOG_FILE_PATH).

Known Issues / TODO

Persistent storage: Elements are stored in-memory — restarting the server clears everything. Use export / snapshots as a workaround.
Mermaid conversion requires a browser: mermaid / create_from_mermaid lay out the diagram in the frontend. Image export and screenshots are headless since v2.1.
Canvas page fonts come from a CDN: serving them from the canvas server would make the page work fully offline.

Contributions welcome!

Development

npm run type-check
npm run build
npm run cli -- status      # run the CLI from the local build
npm run sync:skills        # after editing skills/excalidraw-skill, sync the repo-local agent copy

Bug reports and pull requests are welcome on GitHub issues. If this project helps you, a ⭐ helps others find it.

License

MIT © yctimlin — not affiliated with the Excalidraw team. Excalidraw is its own MIT-licensed project; this toolkit builds on it with love.

Links: npm package · GitHub · Issues · Demo video

If you're interested in what comes next, follow me on X: @ycalintim.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
assets/fonts		assets/fonts
frontend		frontend
scripts		scripts
skills/excalidraw-skill		skills/excalidraw-skill
src		src
tests/browser		tests/browser
.dockerignore		.dockerignore
.gitignore		.gitignore
Dockerfile		Dockerfile
Dockerfile.canvas		Dockerfile.canvas
LICENSE		LICENSE
README.md		README.md
claude_desktop_config.json		claude_desktop_config.json
demo.gif		demo.gif
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json
playwright.config.mjs		playwright.config.mjs
tsconfig.json		tsconfig.json
vite.config.js		vite.config.js

Latest commit

History

Folders and files

Repository files navigation

Excalidraw MCP Server, CLI & Agent Skill

Demo

Table of Contents

What It Is

How We Differ from the Official Excalidraw MCP

What's New

v2.1.2 — Fixes

v2.1.1 — Fixes

v2.1 — Headless Rendering

v2.0 — Interchange-Grade Exports & MCP 2026-07-28

v1.1 — CLI-First

Installation

Easiest: let your agent install it

Manual install

60-Second Quick Start (CLI)

Agent Skill

CLI Reference

Headless Rendering

Configure MCP Clients

Environment Variables

Claude Desktop

Claude Code

Cursor

Codex CLI

OpenCode

Antigravity (Google)

Notes

MCP Tools (26 Total)

Quick Start (From Source / Docker)

Testing

CLI Smoke Test

Canvas Smoke Test (HTTP)

Regression Checks

Canvas Browser Regression Tests

MCP Stdio Wire Test

MCP Smoke Test (MCP Inspector)

Frontend Screenshots (agent-browser)

FAQ

How is this different from the official Excalidraw MCP?

Which AI tools does it work with?

Can the AI actually see the diagram it drew?

Do I need a browser open?

Are my diagrams persistent?

Are excalidraw.com share links private?

Does it need an API key or cloud service?

Can I use it without configuring MCP?

Troubleshooting

Known Issues / TODO

Development

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages