Excalidraw MCP Server & CLI
A live Excalidraw canvas workbench for AI coding agents to create, edit, and export diagrams programmatically.
- Source repo
- yctimlin/mcp_excalidraw
- Stars
- ★ 2.5k
- Last updated
- 9d ago
- License
- MIT
- Primary language
- TypeScript
- FA score
- 59/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformChatGPT · Codex · Claude Code · Claude.ai
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- An architect uses Claude Code to generate an architecture diagram from a text description and automatically layout the elements.
- Not a fit if
- CI pipelines needing headless screenshots without a browser tab
- Teams needing canvas state to survive a server restart
- Deployments exposed to a network that need built-in authentication
- Source review
- 59/100 · Major gaps
What does this agent do, and when should you use it?
mcp-excalidraw-server provides AI agents a local canvas server that exposes a programmatic Excalidraw canvas. It offers three interfaces: CLI (recommended for coding agents), MCP server (26 tools), and REST API. Core drawing is fully local, requires no API keys, and only needs Node.js ≥ 18. Agents can create elements, query them, take screenshots, refine layouts iteratively, and export diagrams as .excalidraw files to commit alongside code. The canvas server supports real-time sync and named server-side snapshots. It differs from the official Excalidraw MCP by focusing on a persistent canvas workbench for coding agents, not a one-shot chat widget.
The tool starts a local Excalidraw canvas server (default port 3000) with a REST API and WebSocket real-time sync. Agents can drive the canvas either via CLI commands (add, query, describe, screenshot, export, import, mermaid, snapshot, arrange) or MCP tools (create_element, query_elements, get_canvas_screenshot, export_scene). It can create elements like rectangles with text and arrows, query elements, see the canvas via screenshots, align/distribute/group/lock elements, export to .excalidraw or .excalidraw.md (Obsidian) formats, create diagrams from Mermaid, and save named snapshots. Elements are stored in-memory on the server, so persistence is achieved via export or snapshots. It also provides an optional share command that uploads an encrypted scene to excalidraw.com.
- An architect uses Claude Code to generate an architecture diagram from a text description and automatically layout the elements.
- A developer updates architecture diagrams in documentation after code changes by re-importing and editing .excalidraw files.
- Obsidian users export diagrams as .excalidraw.md files to embed directly into notes with the Obsidian Excalidraw plugin.
- CI pipelines generate diagrams headlessly via CLI as build artifacts, without needing MCP configuration.
- Agents in Cursor or Codex CLI create flowcharts on the fly and iterate with the agent's help.
How do you install or deploy this agent?
Prerequisite: Node.js ≥ 18. No clone or MCP configuration is required; use npx directly. For MCP clients, add the config as per the README. For coding agents, recommended: run npx -y mcp-excalidraw-server install-skill --dir <skills-root>.
How do you use this agent?
1) Start the canvas: npx -y mcp-excalidraw-server start, then open http://127.0.0.1:3000 in a browser to enable screenshots and Mermaid. 2) Add elements: echo '[{"id":"api","type":"rectangle",...}]' | npx -y mcp-excalidraw-server add. 3) Inspect: npx -y mcp-excalidraw-server describe and screenshot. 4) Export: npx -y mcp-excalidraw-server export --out docs/architecture.excalidraw. The CLI auto-starts the server if needed.
What are this agent's strengths and limitations?
- Element-level CRUD and layout tools (align, distribute, group, lock) far beyond the official MCP's capabilities.
- Screenshot and structured text descriptions let agents self-verify and fix layout issues.
- Fully local, no API keys, MIT licensed, and free to use.
- Offers CLI, MCP, and REST interfaces, making it usable from many agents and frameworks.
- Canvas state is stored in-memory and lost on server restart; requires explicit export or snapshots.
- Screenshots, image export, and Mermaid conversion require a browser tab open to the canvas URL; not headless.
- Docker setup requires network configuration (e.g., host.docker.internal) and the Docker MCP image cannot auto-start the canvas server.
How does this agent compare with similar options?
Compared to the official Excalidraw MCP, this project provides a persistent canvas with fine-grained control (element CRUD, layout tools, screenshot feedback), whereas the official one is a one-shot chat widget with only two tools.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Excalidraw MCP Server & CLI This agent | 59 · Major gaps | CLIFree | ★ 2.5k | 9d ago | TypeScript | ChatGPT · Codex · Claude Code · Claude.ai |
| OSS Autopilot | 83 · Good | Agent plugin / skillFree | ★ 21 | 1d ago | TypeScript | Claude Code · Claude.ai |
| Context | 74 · Some gaps | MCP serverFree | ★ 424 | 1d ago | TypeScript | Codex · Claude Code · Claude.ai |
| REA: Reverse Engineer Anything with Agents | 72 · Some gaps | CLIFree | ★ 327k | today | TypeScript | Codex · Claude Code · Claude.ai |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: default binds to 127.0.0.1, environment variables like EXCALIDRAW_NO_AUTOSTART control auto-start, export directory configurable, snapshots and rollback exist. Deductions: clear command requires --yes confirmation, but other destructive operations (delete, update) lack explicit confirmation; data flow transparency partially documented, but not all network requests detailed; sensitive data handling: share claims encrypted upload but no implementation details; dependency security: no audit or vulnerability scan evidence; external effects: network service and file writes, but default local bind with security note; rollback: snapshots exist but full rollback process not detailed; source attribution: author info in package.json but publisher unverified.
Evidence shows: README, CLI reference, MCP tool list internally consistent, version numbers match; dependencies listed in package.json, CI and Docker builds exist, but no dependency availability tests; failure messages: CLI has exit codes and stderr diagnostics, but no specific error message examples. Deductions: dependency availability not fully verified, failure messages lack concrete examples.
Evidence shows: clearly targets coding agents (Claude Code, Codex, etc.), provides multiple usage scenarios (CLI, MCP, REST); capability boundaries clear, distinguishing local drawing and optional sharing; trigger precision: CLI commands and MCP tools well-defined; environment fit: supports Node>=20, Docker, multiple client configs. Deductions: no detailed error handling or edge case documentation.
Evidence shows: README well-structured with TOC; installation instructions detailed (npx, Docker, source); naming stable, CLI and MCP tool names consistent; examples and FAQ provided; known limitations mentioned; MIT license clear; version and changelog in README; maintenance responsibility: author info present but no explicit maintenance commitment. Deductions: maintenance responsibility not explicit, publisher unverified.
Evidence shows: output usability high, supports multiple export formats and screenshots; marginal value clear, provides features official MCP lacks; cost-benefit: local run without API keys, but requires Node and browser. Deductions: no performance or resource consumption data.
Evidence shows: README claims align with code and config, e.g., Node version, MCP protocol version; CI and test scripts exist but no test results; fact/inference separation: README distinguishes feature descriptions and design intent. Deductions: cross-source corroboration insufficient, no independent testing or third-party verification.
- Publisher identity unverified; check source before installation.
- Share feature claims encrypted upload but no implementation details; use with caution.
- Dependency security lacks audit evidence; consider running npm audit.
- Destructive operations (delete, update) lack user confirmation; risk of accidental changes.
- In-memory storage; data lost on restart; export or snapshot regularly.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
Fixes - Snapshot restore and import are atomic: a rejected restore or replace-import no longer wipes the canvas. Native frames now restore, import, export and can be created through the CLI and MCP. (#101, thanks @sanjayy0612; #120) - One label per shape: updating or renaming a labelled shape while a canvas tab is open no longer stacks duplicate labels. (#121, thanks @sdrshn-nmbr) - Dropped images survive reload: the tab uploads image files on sync (only new ones), so they persist and appear in exports and headless screenshots. (#122, thanks @appdesigngeeks) …View on GitHub ↗ -
Release notes excerpt
Fixes - Exports always load: valid order keys, so saved scenes with more than about 45 labelled shapes no longer fail with invalid order key. Free text exports left/top aligned, like the canvas. (#115, thanks @fernandovmacedo) - No more drift on sync: center- and right-aligned text, labels on arrows, and arrows no longer move or shrink each time an open canvas tab syncs. Text x/y is always the top-left corner. (#116, thanks @hidinginabunker) …View on GitHub ↗ -
v2.1.0 v2.1.0 — Headless Rendering
Release notes excerpt
What's Changed * Dev by @yctimlin in https://github.com/yctimlin/mcp_excalidraw/pull/11 * Support windows by @PhantomPayne in https://github.com/yctimlin/mcp_excalidraw/pull/13 * Fix MCP delete/update methods and add frontend sync functionality by @Songmengdi in https://github.com/yctimlin/mcp_excalidraw/pull/19 * Dev by @yctimlin in https://github.com/yctimlin/mcp_excalidraw/pull/21 * docs: set figure aligned by @ctchen222 in https://github.com/yctimlin/mcp_excalidraw/pull/25 * Fixes group_elements operation by @gianluca-venturini in https://github.com/yctimlin/mcp_excalidraw/pull/27 …View on GitHub ↗