excalidraw-mcp
excalidraw-mcp is a self-hosted MCP server for programmatic Excalidraw authoring.
The goal is not just to mutate scene JSON. The server gives agents a safer abstraction over Excalidraw so they can:
- create and refine scenes without hand-managing fragile internals
- use higher-level authoring helpers for nodes, flows, swimlanes, frames, layers, and styling
- analyze quality before export
- apply deterministic cleanup before final polish
- export offline through a local Excalidraw bundle
- optionally import scenes into authenticated Excalidraw / Excalidraw+ accounts
Documentation
- Architecture:
docs/ARCHITECTURE.md - Tool reference:
docs/TOOL_REFERENCE.md - Capability matrix:
docs/CAPABILITY_MATRIX.md - Agent playbook:
docs/AGENT_PLAYBOOK.md - Claude client setup:
docs/CLAUDE_CLIENTS.md - Account linking:
docs/ACCOUNT_LINKING.md - Bundled Agent Skill:
skills/excalidraw-agent/SKILL.md
What’s In The Server
- Scene lifecycle, patching, app state, files, library items, Mermaid conversion, and exports
- Deterministic layout helpers:
elements_arrangelayout_flowlayout_swimlaneslayout_polish- Higher-level authoring helpers:
diagram_composeelements_create_skeletonsnodes_createnodes_composeframes_createframes_assign_elementsstyles_apply_presetlayers_reorder- Quality and repair helpers:
scene_validatescene_normalizescene_analyzescene_quality_gate- Resources including:
excalidraw://scenesexcalidraw://scene/{sceneId}/summaryexcalidraw://scene/{sceneId}/analysisexcalidraw://scene/{sceneId}/jsonexcalidraw://docs(index of bundled skill references)excalidraw://docs/{topic}(e.g.excalidraw-troubleshooting,excalidraw-install-and-integration)- Prompts for planning, refinement, conversion, and review
Agent Workflow
Recommended loop for agents:
scene_analyze- Deterministic helpers:
nodes_compose,layout_swimlanes,layout_flow,layout_polish,styles_apply_preset,frames_assign_elements scene_validatescene_quality_gateexport_svg/export_png/export_webp
Use scene_normalize first whenever analysis shows structural issues such as broken bindings, missing container backlinks, missing files, or invalid geometry.
If the client supports MCP prompts, start with agent-workflow-guide for an in-band summary of the preferred tool-selection strategy.
Worked Example: Semantic Node```json
{
"name": "nodes_compose",
"arguments": {
"sceneId": "system-map",
"preset": "process",
"nodes": [
{
"nodeId": "api",
"x": 120,
"y": 140,
"width": 240,
"minHeight": 132,
"title": "API Gateway",
"body": "Receives requests, validates auth, and routes traffic.",
"iconText": "API"
}
]
}
}
### Worked Example: Swimlanes```json
{
"name": "layout_swimlanes",
"arguments": {
"sceneId": "system-map",
"laneArrangement": "columns",
"originX": 40,
"originY": 80,
"laneWidth": 320,
"laneHeight": 260,
"lanes": [
{ "laneId": "lane-intake", "label": "Intake", "elementIds": ["api"] },
{
"laneId": "lane-processing",
"label": "Processing",
"elementIds": ["worker"]
}
]
}
}
Quality Model
scene_analyze reports:
- scene bounds and graph summary
- overlaps and dense clusters
- off-canvas elements
- connector crossings
- typography inconsistency
- unreadable text
- missing titles and legends
- container/frame/file integrity issues
recommendedActionsthat point to deterministic next tools
layout_polish is intentionally conservative. It resolves deterministic layout problems like overlap, spacing, connector label recentering, and supporting-text rebalance without inventing new semantic content.
Presets
Built-in presets:
processdecisionnotetitlelegendaccentswimlaneboundarysupporting_text
All higher-level authoring helpers share the same spacing and typography scale:
- spacing:
8 / 16 / 24 / 32 / 48 / 72 - text:
30 / 18 / 16 / 14 - node padding:
20 - frame/lane padding:
24
Runtime Model
- JSON engine for deterministic scene operations and normalization
- Local browser engine (Playwright + Chromium) for offline Excalidraw-native export
- Local Excalidraw runtime bundle checked into the repo for export/repair parity
- Workspace-backed storage under
.excalidraw-mcp/
Install```bash
npm install
Playwright browser install if needed:```bash
npx playwright install chromium
Run
Stdio```bash
npm run dev
or
npm run start:stdio
### HTTP```bash
npm run dev:http
# or
npm run start:http
Optional environment variables:
MCP_HTTP_HOSTdefault127.0.0.1MCP_HTTP_PORTdefault8788MCP_HTTP_PATHdefault/mcpMCP_WORKSPACE_ROOTdefault current working directory
Claude Clients
Claude Code and Claude Desktop should both point at the built stdio server:```bash
node /Users/workboi/projects/excalidraw-mcp/dist/src/index.js --transport stdio
Use `MCP_WORKSPACE_ROOT=/Users/workboi/projects/excalidraw-mcp`. Full setup and verification commands are in `docs/CLAUDE_CLIENTS.md`.
## Verification
Main local gate:```bash
npm test
npm run typecheck
npm run lint
npm run build
Extra smoke paths:```bash
npm run smoke:dist
npm run smoke:account:plus
npm run smoke:account:excalidraw
Notes:
- `smoke:dist` exercises the built `dist` server over stdio.
- `smoke:account:*` are opt-in manual checks and require a real authenticated browser session.
## Visual Regression
The repo includes structural fixture tests and committed canonicalized SVG goldens for:
- simple flow
- process board
- swimlane board
- frame-based architecture
Agent release E2E coverage also exercises MCP-client workflows for semantic compose, manual repair, quality gates, and all export formats.
Refresh goldens intentionally only:```bash
UPDATE_GOLDENS=1 npx vitest run test/integration/visual.goldens.test.ts
Account Linking Quick Start
- Prepare a headed login session:```json
{
"name": "account_login_session",
"arguments": {
"destination": "plus",
"mode": "headed",
"session": "main-profile",
"timeoutSec": 300,
"closeOnComplete": false
}
}
2. Import a scene:```json
{
"name": "account_import_scene",
"arguments": {
"sceneId": "my-scene",
"destination": "plus",
"mode": "headed",
"session": "main-profile",
"allowInteractiveLogin": false
}
}
- Inspect recent status:```json
{
"name": "account_link_status",
"arguments": {
"session": "main-profile"
}
}
Account results now include explicit `reasonCode` values like `READY`, `AUTH_NOT_READY`, `IMPORTED`, `IMPORT_STRATEGY_FAILED`, and `POST_IMPORT_VERIFICATION_FAILED`.
## Demo
Generate a realistic sales-process board through the MCP server itself:```bash
node scripts/demo-sales-process-board.mjs
Artifacts are written under tmp/generated/sales-process-overview/.
Bundled Agent Skill
This repo ships an Anthropic Agent Skill at
skills/excalidraw-agent/. It gives agent clients procedural
guidance for embedding Excalidraw in React/Next.js host apps, troubleshooting runtime
issues, and orchestrating the snake_case MCP tools above. Its reference files are also
served by this MCP server as excalidraw://docs/{topic} resources, so MCP-only clients can
read them without filesystem access.
Install into your agent client by symlinking the directory:```bash
ln -s "$PWD/skills/excalidraw-agent" ~/.claude/skills/excalidraw-agent # Claude Code
ln -s "$PWD/skills/excalidraw-agent" ~/.codex/skills/excalidraw-agent # Codex
ln -s "$PWD/skills/excalidraw-agent" ~/.cursor/skills/excalidraw-agent # Cursor
ln -s "$PWD/skills/excalidraw-agent" ~/.config/zed/skills/excalidraw-agent # Zed
Validate the skill metadata:```bash
npx --yes skills-ref validate skills/excalidraw-agent
The skill no longer ships its own bash scripts — all execution work routes through the MCP
tools in this server.
For Agent Authors
If you are wiring this server into another agent stack, the best onboarding path is:
- read
docs/AGENT_PLAYBOOK.md - inspect
docs/TOOL_REFERENCE.md - use the
agent-workflow-guideprompt - prefer
nodes_compose,layout_swimlanes,layout_flow,layout_polish, andstyles_apply_presetover raw patching - install the bundled
skills/excalidraw-agentfor in-band procedural guidance
