excalidraw-mcp

An MCP (Model Context Protocol) server for Excalidraw. It lets an AI agent build, edit, organize, and export Excalidraw scenes — architecture diagrams, flowcharts, codebase maps, whiteboards — entirely headless, producing .excalidraw files you can open at excalidraw.com, plus SVG/PNG renders in Excalidraw's hand-drawn style.

<p align="center"><img src="examples/flowchart.png" width="420" alt="Flowchart generated by the smoke test" /></p>

Features

• Every element type: rectangles, ellipses, diamonds, text, lines, arrows, freedraw strokes, frames, embedded images, and embeddables (iframes)
• Real Excalidraw semantics: bound labels (text inside shapes / on arrows), arrow ↔ shape bindings that survive dragging in the UI, groups, frames, z-order, lock state, fractional indices
• One-shot diagrams: create_flowchart lays out labeled nodes and bound edges automatically (layered layout, down or right)
• Full editing surface: update, move, resize, duplicate (with binding remap), align, distribute, group, reorder, query
• Overlap-free by default: creation tools nudge new elements to free space (avoidOverlap: false to layer intentionally), resolve_overlaps spreads out colliding elements, and bound arrows re-route automatically after moves
• Persistence & export: .excalidraw files (v2), .excalidrawlib libraries, SVG and PNG rendering (roughjs + perfect-freehand, so it looks like Excalidraw)
• All three MCP primitives: 42 tools, resources (excalidraw://scenes, excalidraw://scene/{id}, excalidraw://scene/{id}/svg), and prompts (architecture-diagram, flowchart, annotate-scene)

Setup

npm install
npm run build

Claude Code

claude mcp add excalidraw -- node /path/to/excalidraw-mcp/dist/index.js

(This repo also ships a project-scoped .mcp.json, so opening the repo in Claude Code registers the server automatically.)

Claude Desktop

// claude_desktop_config.json
{
  "mcpServers": {
    "excalidraw": {
      "command": "node",
      "args": ["/path/to/excalidraw-mcp/dist/index.js"]
    }
  }
}

Tools

Group	Tools
Scenes	create_scene list_scenes switch_scene get_scene describe_scene clear_scene delete_scene set_app_state save_scene load_scene unlock_all
Create	add_shape add_text add_line add_arrow add_freedraw add_frame add_image add_embed add_elements
Edit	get_element find_elements update_element delete_elements duplicate_elements move_elements resize_element
Organize	connect_elements add_label group_elements ungroup_elements align_elements distribute_elements resolve_overlaps reorder_elements lock_elements add_to_frame
Export	export_svg export_png export_library import_library
Diagrams	create_flowchart

Typical flow:

1. create_scene
2. add_shape / add_text / create_flowchart, then connect_elements to wire things up
3. describe_scene to verify
4. save_scene → open the .excalidraw file at excalidraw.com, and/or export_svg / export_png for a preview

Example — the whole auth flowchart above is one call:

{
  "name": "create_flowchart",
  "arguments": {
    "nodes": [
      { "id": "start", "label": "Request", "shape": "ellipse", "backgroundColor": "#b2f2bb" },
      { "id": "auth", "label": "Authenticated?", "shape": "diamond", "backgroundColor": "#ffec99" },
      { "id": "handler", "label": "Route handler" },
      { "id": "reject", "label": "401 Unauthorized", "backgroundColor": "#ffc9c9" },
      { "id": "db", "label": "Database" }
    ],
    "edges": [
      { "from": "start", "to": "auth" },
      { "from": "auth", "to": "handler", "label": "yes" },
      { "from": "auth", "to": "reject", "label": "no", "strokeStyle": "dashed" },
      { "from": "handler", "to": "db", "label": "query" }
    ]
  }
}

Notes

• Coordinates: y grows downward; shapes are positioned by their top-left corner.
• PNG export uses the optional @resvg/resvg-js dependency; SVG export has no native dependencies.
• Text sizing is estimated headlessly (~0.6em per character); Excalidraw re-measures precisely when a file is opened.

Development

npm run build   # compile TypeScript
npm test        # end-to-end smoke test (spawns the server with a real MCP client)

The smoke test writes example output (demo.excalidraw, flowchart.excalidraw, SVG/PNG renders, a .excalidrawlib) into examples/.