mcp-excalidraw
About
MCP server and Claude Code skill for Excalidraw — programmatic canvas toolkit to create, edit, and export diagrams via AI agents with real-time canvas sync.
Details
- License
- MIT
Explore
- 26 MCP tools for full element-level CRUD, layout, snapshots, and file I/O.
- CLI-first – composable commands with JSON output and meaningful exit codes.
- Auto‑starting canvas server – no separate setup for drawing commands.
- Agent sees the canvas – describe (structured text) and screenshot (image) enable iterative refinement.
- Mermaid conversion – mermaid / create_from_mermaid and share for encrypted URLs.
- Multi‑agent support – multiple agents on the same canvas concurrently.
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
mcp-excalidrawCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
The only prerequisite is Node.js ≥ 18.
Copy this into your coding agent — it installs the portable skill into the project/global skill directory that agent already knows how to use, then verifies it by drawing a test diagram:
Install the Excalidraw canvas toolkit so you can draw diagrams for me:
1. Choose the right skill directory for this agent and scope (project or global).
2. Run: npx -y mcp-excalidraw-server install-skill --dir <that-skills-directory>
3. Read the installed excalidraw-skill/SKILL.md so you know the drawing workflow.
4. Start the canvas with: npx -y mcp-excalidraw-server start
then tell me to open http://127.0.0.1:3000 in my browser (screenshots need an open tab).
5. Draw a small test diagram — two labeled boxes connected by an arrow — take a
screenshot, and show me the result to confirm everything works.
| You are... | Install with | Then |
|---|---|---|
| Modern coding agent | npx -y mcp-excalidraw-server install-skill --dir <skills-root> | Let the agent choose project/global scope and its skill root |
| Claude Code shortcut | npx -y mcp-excalidraw-server install-skill | Installs to ~/.claude/skills for backward compatibility |
| Codex shortcut | npx -y mcp-excalidraw-server install-skill --target codex | Installs to ~/.codex/skills for backward compatibility |
| MCP client user (Claude Desktop, Cursor, ...) | Add the npx config below | See Configure MCP Clients |
| CLI user / scripting | Nothing — npx -y mcp-excalidraw-server <command> | See CLI Reference |
| Contributor / from source | git clone + npm ci + npm run build | See Quick Start (From Source / Docker) |
There is no separate server setup: any drawing command auto-starts the local canvas server on http://127.0.0.1:3000.
No clone, no config:
The MCP server runs over stdio. Since v1.1 the simplest config is npx — no clone, no absolute paths, and the canvas auto-starts:
| Variable | Description | Default |
|----------|-------------|---------|
| EXPRESS_SERVER_URL | URL of the canvas server | http://127.0.0.1:3000 |
| ENABLE_CANVAS_SYNC | Enable real-time canvas sync | true |
| EXCALIDRAW_NO_AUTOSTART | Set 1 to disable canvas auto-start | (unset) |
| EXCALIDRAW_EXPORT_DIR | Base directory MCP file exports may write to | current working dir |
| PORT / HOST | Canvas server bind address | 3000 / 127.0.0.1 |
---
From source (Node >= 18):
npm ci
npm run build
PORT=3000 npm run canvas # canvas server (terminal 1)
node dist/index.js # MCP server over stdio (terminal 2, usually launched by your MCP client)
node dist/bin.js status # or drive the CLI straight from the build
Docker canvas server:
docker run -d -p 3000:3000 --name mcp-excalidraw-canvas ghcr.io/yctimlin/mcp_excalidraw-canvas:latest
``
MCP server image:
ghcr.io/yctimlin/mcp_excalidraw:latest (stdio; point EXPRESS_SERVER_URL at the canvas container).
Yes — that's the recommended path for coding agents:
npx -y mcp-excalidraw-server install-skill --dir <skills-root>` and the agent drives everything through the CLI. MCP configuration is only needed for chat clients like Claude Desktop.Category
Tools
| Category | Tools |
|---|---|
| Element CRUD | create_element, get_element, update_element, delete_element, query_elements, batch_create_elements, duplicate_elements |
| Layout | align_elements, distribute_elements, group_elements, ungroup_elements, lock_elements, unlock_elements |
| Scene Awareness | describe_scene, get_canvas_screenshot |
| File I/O | export_scene, import_scene, export_to_image, export_to_excalidraw_url, create_from_mermaid |
| State Management | clear_canvas, snapshot_scene, restore_snapshot |
| Viewport | set_viewport |
| Design Guide | read_diagram_guide |
| Resources | get_resource |
Full schemas are discoverable via tools/list or in skills/excalidraw-skill/references/cheatsheet.md.
Claude Code, Claude Desktop, Cursor, Codex CLI, OpenCode, and Google Antigravity are documented below — but any agent that can run shell commands can use the CLI, any MCP client can use the MCP server, and anything else (LangChain, custom apps) can use the REST API.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"mcp-excalidraw": {
"mcp_excalidraw": {
"command": "docker",
"args": [
"build",
"-t",
"mcp/excalidraw",
"."
]
}
}
}
}McpServers
{
"mcp_excalidraw": {
"command": "docker",
"args": [
"build",
"-t",
"mcp/excalidraw",
"."
]
}
}Excalidraw MCP Server, CLI & Agent Skill
mcp-excalidraw-server gives AI agents a live Excalidraw canvas they can draw on, look at, refine, and save into your repo. Your agent creates architecture diagrams and flowcharts programmatically, sees its own work via screenshots, fixes layout problems, and exports .excalidraw files you can commit next to your code.
One canvas, three ways to drive it:
- Agent Skill + CLI — recommended for coding agents (Claude Code, Codex CLI, Cursor, OpenCode): npx -y mcp-excalidraw-server <command>. Zero config, auto-starts the canvas, composable JSON in/out.
- MCP Server — 26 tools over stdio for any Model Context Protocol client (Claude Desktop, Cursor, Codex CLI, Antigravity, ...).
- REST API — plain HTTP for LangChain and custom frameworks.
Core drawing runs fully local (Node ≥ 18, MIT licensed) — no API keys. Mermaid conversion runs in the local browser canvas; share is optional and uploads an encrypted scene to excalidraw.com.
Demo
AI agent creates a complete architecture diagram from a single prompt (4x speed). Watch full video on YouTube
Table of Contents
- Demo
- What It Is
- How We Differ from the Official Excalidraw MCP
- What's New
- Installation
- Agent Skill
- CLI Reference
- Configure MCP Clients
- Claude Desktop
- Claude Code
- Cursor
- Codex CLI
- OpenCode
- Antigravity (Google)
- MCP Tools (26 Total)
- Quick Start (From Source / Docker)
- Testing
- FAQ
- Troubleshooting
- Known Issues / TODO
- Development
- License
What It Is
Ask your agent to "draw the architecture of this service" and it produces a real, editable Excalidraw diagram — not a one-shot image. Because the agent can query, screenshot, and update individual elements, it iterates until labels fit, nothing overlaps, and arrows route cleanly; then it exports the result as a .excalidraw file that lives in your repo and gets updated when the code changes.
Under the hood there are two processes, one product:
- Canvas server: Excalidraw web UI + REST API + WebSocket real-time sync (default http://127.0.0.1:3000)
- A thin front-end of your choice: the CLI, the MCP stdio server, or raw HTTP — all drive the same canvas
Since v1.1 the canvas server starts itself: canvas-driving CLI commands (and the MCP server on launch) auto-spawn it if nothing is listening. status only inspects the current server state. Set EXCALIDRAW_NO_AUTOSTART=1 to opt out.
How We Differ from the Official Excalidraw MCP
Excalidraw has an official MCP — a chat widget that streams a diagram inline from a single prompt (the model gets two tools: a format reference and create_view). It's great for "draw me a cat" in Claude or ChatGPT. We solve a different problem: giving coding agents a persistent canvas workbench.
| | Official Excalidraw MCP | This Project |
|---|---|---|
| Approach | Prompt in, diagram out (one-shot widget) | Programmatic element-level control (CLI + 26 MCP tools) |
| State | Checkpoints inside the chat widget | Persistent live canvas with real-time sync |
| Element CRUD | Declarative re-send with delete markers | Full create / read / update / delete per element |
| AI sees the canvas | No | describe (structured text) + screenshot (image) |
| Iterative refinement | Regenerate from checkpoint | Draw → look → adjust → look again, element by element |
| Layout tools | No | align, distribute, group / ungroup, lock, duplicate |
| File I/O | No model-facing export | .excalidraw export/import — diagrams as repo artifacts |
| Snapshot & rollback | Widget-side checkpoints | Named server-side snapshots |
| Mermaid conversion | No | mermaid / create_from_mermaid |
| Shareable URLs | Widget-only | share / export_to_excalidraw_url |
| Works without MCP | No | Yes — CLI + agent skill + REST API |
| Multi-agent | Single chat | Multiple agents on the same canvas concurrently |
TL;DR — The official MCP shows Excalidraw diagrams in your chat. This project gives your coding agent a full Excalidraw workbench: a canvas it can draw on, inspect, refine, and commit to your repo.
What's New
Current package version: 1.1.0. The current release line is v1.1 — CLI-First.
v1.1 — CLI-First
- First-class CLI: every capability is now a composable command — npx -y mcp-excalidraw-server add|query|describe|screenshot|export|import|mermaid|snapshot|arrange|share|... — JSON on stdout, meaningful exit codes. Also installed as the excalidraw-canvas alias.
- Zero-setup: canvas-driving CLI commands and the MCP server auto-start the canvas server if it isn't running (closes #66). Opt out with EXCALIDRAW_NO_AUTOSTART=1.
- apply: multi-op patches ({"create":[...],"update":[{"id":"a","set":{...}}],"delete":[...]}) in a single invocation.
- install-skill: npx -y mcp-excalidraw-server install-skill --dir <skills-root> copies the portable agent skill into the directory your agent chooses (project or global), cleanly replacing older versions.
- Skill is now CLI-first and no longer needs a cloned repo or configured MCP server to work.
- Typed queries: query --filter locked=true --filter label.text=API — booleans, numbers, and nested keys work.
- Internals: shared core library (src/core/) behind both the CLI and MCP server; canvas groupIds are the source of truth for grouping (ungroup now works across restarts); node-fetch dropped; MCP version metadata derived from package.json; canvas server writes a pidfile and shuts down cleanly.
Installation
The only prerequisite is Node.js ≥ 18.
Easiest: let your agent install it
Copy this into your coding agent — it installs the portable skill into the project/global skill directory that agent already knows how to use, then verifies it by drawing a test diagram:
Install the Excalidraw canvas toolkit so you can draw diagrams for me:
1. Choose the right skill directory for this agent and scope (project or global).
2. Run: npx -y mcp-excalidraw-server install-skill --dir <that-skills-directory>
3. Read the installed excalidraw-skill/SKILL.md so you know the drawing workflow.
4. Start the canvas with: npx -y mcp-excalidraw-server start
then tell me to open http://127.0.0.1:3000 in my browser (screenshots need an open tab).
5. Draw a small test diagram — two labeled boxes connected by an arrow — take a
screenshot, and show me the result to confirm everything works.
Manual install
…
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
