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

Table of Contents

• Demo
• What It Is
• How We Differ from the Official Excalidraw MCP
• What's New
• Installation
• Agent Skill
• CLI Reference
• Headless Rendering
• Configure MCP Clients
• Claude Desktop
• Claude Code
• Cursor
• Codex CLI
• OpenCode
• Antigravity (Google)
• MCP Tools (26 Total)
• Quick Start (From Source / Docker)
• Testing
• FAQ
• Troubleshooting
• Known Issues / TODO
• Development
• License

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.

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)