README.md
Run a live Excalidraw canvas and control it from AI agents.
Excalidraw MCP Server & Agent Skill
Run a live Excalidraw canvas and control it from AI agents. This repo provides:
- MCP Server: Connect via Model Context Protocol (Claude Desktop, Cursor, Codex CLI, etc.)
- Agent Skill: Portable skill for Claude Code, Codex CLI, and other skill-enabled agents
Keywords: Excalidraw agent skill, Excalidraw MCP server, AI diagramming, Claude Code skill, Codex CLI skill, Claude Desktop MCP, Cursor MCP, Mermaid to Excalidraw.
Demo
AI agent creates a complete architecture diagram from a single prompt (4x speed). Watch full video on YouTube
What It Is
This repo contains two separate processes:
- Canvas server: web UI + REST API + WebSocket updates (default
http://localhost:3000) - MCP server: exposes MCP tools over stdio; syncs to the canvas via
EXPRESS_SERVER_URL
How We Differ from the Official Excalidraw MCP
Excalidraw now has an official MCP — it's great for quick, prompt-to-diagram generation rendered inline in chat. We solve a different problem.
| Official Excalidraw MCP | This Project | |
|---|---|---|
| Approach | Prompt in, diagram out (one-shot) | Programmatic element-level control (26 tools) |
| State | Stateless — each call is independent | Persistent live canvas with real-time sync |
| Element CRUD | No | Full create / read / update / delete per element |
| AI sees the canvas | No | describe_scene (structured text) + get_canvas_screenshot (image) |
| Iterative refinement | No — regenerate the whole diagram | Draw → look → adjust → look again, element by element |
| Layout tools | No | align_elements, distribute_elements, group / ungroup |
| File I/O | No | export_scene / import_scene (.excalidraw JSON) |
| Snapshot & rollback | No | snapshot_scene / restore_snapshot |
| Mermaid conversion | No | create_from_mermaid |
| Shareable URLs | Yes | Yes — export_to_excalidraw_url |
| Design guide | read_me cheat sheet |
read_diagram_guide (colors, sizing, layout, anti-patterns) |
| Viewport control | Camera animations | set_viewport (zoom-to-fit, center on element, manual zoom) |
| Live canvas UI | Rendered inline in chat | Standalone Excalidraw app synced via WebSocket |
| Multi-agent | Single user | Multiple agents can draw on the same canvas concurrently |
| Works without MCP | No | Yes — REST API fallback via agent skill |
TL;DR — The official MCP generates diagrams. We give AI agents a full canvas toolkit to build, inspect, and iteratively refine diagrams — including the ability to see what they drew.
What's New
v2.0 — Canvas Toolkit
- 13 new MCP tools (26 total):
get_element,clear_canvas,export_scene,import_scene,export_to_image,duplicate_elements,snapshot_scene,restore_snapshot,describe_scene,get_canvas_screenshot,read_diagram_guide,export_to_excalidraw_url,set_viewport - Closed feedback loop: AI can now inspect the canvas (
describe_scene) and see it (get_canvas_screenshotreturns an image) — enabling iterative refinement - Design guide:
read_diagram_guidereturns best-practice color palettes, sizing rules, layout patterns, and anti-patterns — dramatically improves AI-generated diagram quality - Shareable URLs:
export_to_excalidraw_urlencrypts and uploads the scene to excalidraw.com, returns a shareable link anyone can open - Viewport control:
set_viewportwithscrollToContent,scrollToElementId, or manual zoom/offset — agents can auto-fit diagrams after creation - **File I/
Tools (7)
get_elementRetrieve details of a specific element on the canvas.clear_canvasRemove all elements from the current canvas.export_sceneExport the current scene to .excalidraw JSON format.import_sceneImport a scene from .excalidraw JSON format.describe_sceneGet a structured text description of the current canvas state.get_canvas_screenshotCapture and return an image of the current canvas.set_viewportAdjust the camera view, including zoom and centering.Environment Variables
EXPRESS_SERVER_URLThe URL of the running Excalidraw canvas server.Configuration
claude_desktop_config.json
{"mcpServers": {"excalidraw": {"command": "npx", "args": ["-y", "mcp-excalidraw-server"], "env": {"EXPRESS_SERVER_URL": "http://localhost:3000"}}}}Try it
→Create a system architecture diagram for a web application with a frontend, backend, and database.
→Take a screenshot of the current canvas and describe what is missing from the diagram.
→Convert this Mermaid code into an Excalidraw diagram on the canvas.
→Center the view on the database element and zoom in to show its details.
→Apply the standard diagramming guide to improve the layout and colors of the current scene.