yctimlin/mcp_excalidraw

What it does

mcp‑excalidraw‑server turns an Excalidraw canvas into a programmable workbench that AI coding agents (Claude Code, Cursor, Codex CLI, etc.) can drive. The agent can:

• Create, read, update, delete individual diagram elements via JSON commands.
• Take screenshots of the live canvas (now rendered headlessly in Node, no browser needed).
• Iteratively refine a diagram: draw → describe → screenshot → adjust → repeat.
• Export the result as a native .excalidraw file (or Obsidian‑compatible .excalidraw.md) that can be version‑controlled alongside code.
• Import, merge Mermaid diagrams, share encrypted URLs, and take named snapshots.

All of this is exposed through three interchangeable interfaces:

1. CLI (npx -y mcp-excalidraw-server <command>), the recommended way for agents.
2. MCP server that speaks the Model Context Protocol (MCP 2026‑07‑28) for any MCP‑compatible client.
3. REST API for LangChain or custom HTTP callers.

The actual drawing happens locally in a Node ≥ 20 process; no external API keys are required.

---

Who might use it

• Coding assistants that need to generate architecture diagrams, flowcharts, or UI mock‑ups as part of a development workflow.
• CI pipelines that automatically render updated diagrams when source code changes.
• Documentation pipelines (e.g., Obsidian vaults) that keep visual assets in sync with code.
• Teams that want a shared, real‑time canvas that multiple agents can edit concurrently.

---

How to get started

# One‑liner: start the canvas and watch it (optional)
npx -y mcp-excalidraw-server start
open http://127.0.0.1:3000   # view the UI in a browser

# Draw two boxes and an arrow via JSON
cat <<EOF | npx -y mcp-excalidraw-server add
[
  {"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","startElementId":"api","endElementId":"db","text":"SQL"}
]
EOF

# Let the agent see the diagram and capture a PNG
npx -y mcp-excalidraw-server describe
npx -y mcp-excalidraw-server screenshot --out diagram.png

# Save the diagram as a repo artifact
npx -y mcp-excalidraw-server export --out docs/arch.excalidraw

The same commands work inside a Docker container or from source after npm ci.

---

Key features at a glance

Feature	What it gives you
CLI‑first design	All canvas actions are composable JSON commands; exit codes make scripting easy.
MCP compatibility	Works with Claude Desktop, Cursor, Codex CLI, Antigravity, etc., using the latest MCP protocol (no handshake needed).
Headless rendering	Screenshots and image exports are generated inside Node via jsdom + resvg – fast, deterministic, CI‑friendly.
Deterministic exports	Byte‑identical .excalidraw files for unchanged scenes → no noisy git diffs.
Obsidian support	Export to .excalidraw.md for the Obsidian Excalidraw plugin, preserving block references.
Mermaid import	Convert Mermaid text into live Excalidraw elements, merging with existing content.
Snapshot system	Named save/restore points let agents roll back or branch diagram states.
Layout tools	Align, distribute, group/ungroup, lock, duplicate – all via MCP tools or CLI flags.
Shareable URLs	Optional encrypted upload to excalidraw.com for easy sharing.
Zero‑config start	The first drawing command auto‑spawns the canvas server; set EXCALIDRAW_NO_AUTOSTART=1 to disable.

---

Limitations / gotchas

• The server binds only to 127.0.0.1 by default; exposing it externally requires your own network firewall – the API has no built‑in auth.
• Some commands (mermaid conversion, screenshot with --renderer browser) still need an actual browser tab open.
• Requires Node ≥ 20; older versions are not supported.
• Font coverage is limited to the bundled TTFs; exotic scripts fall back to the host OS fonts.

---

License & community

• MIT license – free for commercial and personal use.
• Published on npm as mcp-excalidraw-server (badge shows current version).
• CI badges indicate automated testing and Docker builds.
• Contributions are welcomed; the repo includes a CONTRIBUTING style guide and a development section for building from source.

---

TL;DR

mcp-excalidraw-server is a locally‑run, CLI‑driven Excalidraw canvas that AI coding agents can treat as a mutable drawing surface. It provides element‑level CRUD, headless screenshots, deterministic exports, and full MCP/REST integration, making it easy to generate, refine, and version‑control diagrams directly from AI workflows.