yctimlin/mcp_excalidraw

What the project does

mcp‑excalidraw‑server turns a local Excalidraw canvas into a programmable workbench that AI coding agents (Claude Code, Cursor, Codex, etc.) can drive. The canvas runs completely locally (Node ≥ 20, no API keys) and can be accessed in three ways:

1. CLI – npx -y mcp-excalidraw-server <command> – a set of JSON‑based commands that start the canvas automatically, add/update/delete elements, take screenshots, export files, etc.
2. MCP server – a Model Context Protocol (MCP) stdio server exposing 26 tools, so any MCP‑compatible client can call drawing operations directly.
3. REST API – plain HTTP/WebSocket endpoints for frameworks like LangChain.

The result is a live, mutable diagram that an agent can inspect (via describe or screenshots), refine element‑by‑element, and finally export as a .excalidraw file that lives next to your source code or in an Obsidian vault.

---

Who might use it

• Coding assistants that need to generate architecture diagrams, flowcharts, or UI mock‑ups as part of a development workflow.
• Teams that want diagram files version‑controlled alongside code (e.g., commit .excalidraw files to Git).
• Obsidian users who want to keep diagrams in their vaults with full editability.
• Anyone building a custom AI‑agent toolchain that can call MCP tools or a REST API.

---

Key features (as described in the README)

Feature	What it means
Local canvas server	Runs an Excalidraw web UI on http://127.0.0.1:3000 with real‑time WebSocket sync. No external services required.
CLI‑first design	All capabilities are exposed as composable commands (add, apply, query, screenshot, export, mermaid, snapshot, arrange, share, …). JSON is printed on stdout, exit codes indicate success/failure.
MCP integration	Implements MCP protocol revision 2026‑07‑28; 26 tools let any MCP client (Claude Desktop, Cursor, Codex CLI, Antigravity, etc.) manipulate the canvas via stdio.
REST API	Simple HTTP endpoints for LangChain or custom scripts.
Element‑level CRUD	Create, read, update, delete individual shapes, arrows, text, groups, locks, etc.
Iterative refinement	Agents can describe the scene, take a screenshot, adjust layout, and repeat until the diagram is clean.
Export / Import	Export to native .excalidraw JSON or Obsidian‑compatible .excalidraw.md. Imports support both formats, including compressed vault files.
Deterministic exports	IDs, seeds, and key ordering are stable, so unchanged diagrams produce identical files – no noisy Git diffs.
Mermaid conversion	Paste Mermaid syntax; the server merges the generated diagram into the existing canvas.
Viewport control	Commands to zoom, pan, or fit selected elements.
Share	Optional encrypted upload to excalidraw.com for a shareable URL.
Docker image	Pre‑built container (ghcr.io/yctimlin/mcp_excalidraw) for easy deployment.
Agent skill bundle	A portable skill (skills/excalidraw-skill/) that can be installed into an agent’s skill directory with a single install-skill command.
Zero‑setup auto‑start	CLI commands and the MCP server automatically spawn the canvas if it isn’t already running (unless EXCALIDRAW_NO_AUTOSTART=1).

---

How to get started (quick‑start)

# Install and start the canvas (auto‑starts on first draw command)
npx -y mcp-excalidraw-server start
open http://127.0.0.1:3000   # optional – needed for screenshots/mermaid

# Add two boxes and an arrow (JSON via stdin)
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","startElementId":"api","endElementId":"db","text":"SQL"}
]' | npx -y mcp-excalidraw-server add

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

# Export for version control
npx -y mcp-excalidraw-server export --out docs/architecture.excalidraw

The same commands can be called from any MCP‑compatible client or via HTTP.

---

Limitations / open issues (as listed)

• The server binds only to 127.0.0.1 by default; exposing it externally requires the user to add their own network firewall or reverse‑proxy – there is no built‑in authentication.
• Some operations (e.g., screenshot, mermaid conversion) need an open browser tab because they rely on the client‑side Excalidraw UI.
• The README mentions a few “known issues / TODO” sections but does not enumerate concrete bugs; users should check the issue tracker for the latest status.

---

Who maintains it

The repository is owned by yctimlin and is published on npm as mcp-excalidraw-server (MIT license). Continuous integration runs tests and builds a Docker image on each push.

---

TL;DR

mcp-excalidraw-server gives AI coding agents a real, editable drawing surface they can control programmatically. It works via a simple CLI, an MCP stdio server, or a REST API, and it stores diagrams as version‑controlled .excalidraw files – making it a practical bridge between LLM‑generated architecture ideas and concrete, editable diagrams.