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.

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)

Related MCP server: Excalidraw MCP Server

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

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/.