MCP server and Claude Code skill for Excalidraw — programmatic canvas toolkit to create, edit, and export diagrams via AI agents with real-time canvas sync.
MCP server and Claude Code skill for Excalidraw — programmatic canvas toolkit to create, edit, and export diagrams via AI agents with real-time canvas sync.
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:
npx -y mcp-excalidraw-server <command>. Zero config, auto-starts the canvas, composable JSON in/out.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.Core drawing runs fully local (Node ≥ 20, MIT licensed) — no API keys. Mermaid conversion runs in the local browser canvas; share is optional and uploads an encrypted scene to excalidraw.com.
AI agent creates a complete architecture diagram from a single prompt (4x speed). Watch full video on YouTube
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:
http://127.0.0.1:3000)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.
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.
Current package version: 2.0.0. The current release line is v2.0 — Interchange-Grade Exports & MCP 2026-07-28.
server/discover, per-request _meta envelopes); legacy initialization-based clients keep working unchanged. (#98, thanks @anxkhn).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).excalidraw.md files import correctly (#94, thanks @cason-miles); ## Text Elements block references now cover shape labels too.containerId, textAlign, originalText, ...) pass through the server intact — fixes browser-edited text vanishing after sync. (#92, thanks @junuxyz)set_viewport gains scrollToElementIds (multi-element zoom-to-fit) and viewportZoomFactor, with strict single-mode validation and real error reporting. (#86, thanks @acercyc)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.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.query --filter locked=true --filter label.text=API — booleans, numbers, and nested keys work.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.The only prerequisite is Node.js ≥ 20.
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:
…| 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.
No clone, no config:
…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 pathSecurity note: The canvas server binds
127.0.0.1only 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.
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:
.excalidraw files into the repo, commit them, re-import + refine when the architecture changes..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.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 code
No open issues yet, or sync has not completed.