Provides a comprehensive set of drawing tools to create, update, and manage diagrams in the Excalidraw format, including support for exporting scenes to excalidraw.com.
Enables the conversion of Mermaid diagram definitions into editable Excalidraw canvas elements.
excalidraw-mcp-server
The only Excalidraw MCP server with security hardening, inline diagram rendering, and real-time canvas sync.
What it does
Ask your AI to draw a diagram, and it appears right inside the chat. The MCP server gives Claude Desktop, ChatGPT, VS Code, and Cursor a full set of drawing tools backed by the Excalidraw format -- with API authentication, rate limiting, and input validation on every operation.
v2.0 adds MCP Apps support: diagrams stream inline as interactive SVG widgets with draw-on animations, and you can export any diagram to excalidraw.com with one click.
Two modes, zero config
Standalone mode (default) -- just install and go. The server runs with an in-process element store. No canvas server, no API keys, no setup. Your MCP client calls the tools, and diagrams render inline.
Connected mode -- start the optional canvas server for real-time browser sync. Multiple clients can collaborate on the same canvas through authenticated WebSocket connections. File persistence keeps state across restarts.
The server auto-detects which mode to use: if a canvas server is reachable, it connects to it. Otherwise it falls back to standalone.
Architecture
Diagram created with excalidraw-mcp-server --
Features
MCP Apps (v2.0)
Inline diagram rendering in Claude Desktop, ChatGPT, and VS Code
Streaming SVG with draw-on animations as elements arrive
Export to excalidraw.com with one click
Element reference cheatsheet via
read_metool
16 MCP tools
Create, update, delete, and query elements (rectangle, ellipse, diamond, arrow, text, line, freedraw)
Batch create up to 100 elements at once
Group, ungroup, align, distribute, lock, unlock
Mermaid diagram conversion
SVG and PNG export
Security
API key authentication with constant-time comparison
Origin-restricted CORS (no wildcards)
WebSocket auth with token and origin validation
Standard and strict rate limiting tiers
Bounded Zod schemas with
.strict()on every endpointHelmet.js security headers with CSP
Infrastructure
Real-time WebSocket sync across browser clients
Optional atomic-write file persistence
Structured pino audit logging
Install
Or run directly:
Quick start
Standalone (recommended for most users)
Just point your MCP client at the server. No canvas server needed.
Then ask your AI: "Draw an architecture diagram showing a load balancer, three app servers, and a database"
Connected mode (real-time browser sync)
Point your MCP client at the server with the same API key:
MCP tools
Tool | Description |
| Render elements as an inline SVG widget with streaming animations (MCP Apps) |
| Get the element reference cheatsheet (types, colors, sizing tips) |
| Create a single element (rectangle, ellipse, diamond, arrow, text, line, freedraw) |
| Update an existing element by ID |
| Delete an element by ID |
| Search elements by type, locked status, or group ID |
| Get scene state, all elements, theme, or library |
| Create up to 100 elements in one call |
| Group multiple elements together |
| Remove elements from a group |
| Align elements (left, center, right, top, middle, bottom) |
| Distribute elements evenly (horizontal or vertical) |
| Lock elements to prevent modification |
| Unlock elements |
| Convert a Mermaid diagram to Excalidraw elements |
| Export the canvas as SVG or PNG |
Security comparison
Feature | Typical MCP servers | excalidraw-mcp-server |
Authentication | None | API key (constant-time compare) |
CORS |
| Origin allowlist |
WebSocket auth | None | Token + origin validation |
Rate limiting | None | Standard + strict tiers |
Input validation | Minimal | Bounded Zod with |
Security headers | None | Helmet.js + CSP |
Request size limit | None | 512KB body, 1MB WebSocket |
Audit logging | None | Structured pino logs |
Configuration
All settings via environment variables. Copy .env.example to .env and adjust as needed.
Variable | Default | Description |
|
| Use in-process store (no canvas server needed) |
|
| Canvas server bind address |
|
| Canvas server port |
| Auto-generated | API key for auth (min 32 chars) |
|
| Comma-separated origin allowlist |
|
| Rate limit window in milliseconds |
|
| Max requests per window (standard tier) |
|
| Enable file-based persistence |
|
| Directory for persistent storage |
|
| URL the MCP server uses to reach the canvas |
|
| Log level: debug, info, warn, error |
|
| Enable audit logging |
|
| Maximum elements on canvas |
|
| Maximum elements per batch create |
MCP client configuration
Claude Desktop
Add to claude_desktop_config.json:
Cursor
Add to .cursor/mcp.json in your project root:
VS Code
Add to your MCP settings:
For connected mode, add "env": { "EXCALIDRAW_API_KEY": "<key>", "CANVAS_SERVER_URL": "http://127.0.0.1:3000" } to the config above. Replace <key> with the key from node scripts/generate-api-key.cjs.
Development
Project structure
Migrating from v1.x
Zero-config upgrade. All 14 original tools work identically -- create_view and read_me are additive. The canvas server is now optional (standalone mode activates automatically).
Existing MCP client configs (stdio transport, tool names) continue to work without changes.