Excalidraw MCP Server & CLI
A live Excalidraw canvas workbench for AI coding agents to create, edit, and export diagrams programmatically.
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.
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.
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 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.
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.