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.

	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	Live canvas with real-time sync and optional restart-safe checkpoints
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 browse