# mcp-excalidraw-server [Health: Active]

**Category:** 📐 Architecture & Design  
**Repository:** https://github.com/yctimlin/mcp_excalidraw  
**GitHub Stars:** 2601  
**npm Downloads (last month):** 11147  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/mcp-excalidraw-server

## Description
Excalidraw toolkit for AI coding agents — agent skill, CLI, and MCP server with a live canvas

## Tools
Capabilities this server exposes over MCP:

- **create_element** — Create a new Excalidraw element. For arrows, use startElementId/endElementId to bind to shapes (auto-routes to edges).
- **update_element** — Update an existing Excalidraw element
- **delete_element** — Delete an Excalidraw element
- **query_elements** — Query Excalidraw elements with optional filters
- **get_resource** — Get an Excalidraw resource
- **group_elements** — Group multiple elements together
- **ungroup_elements** — Ungroup a group of elements
- **align_elements** — Align elements to a specific position
- **distribute_elements** — Distribute elements evenly
- **lock_elements** — Lock elements to prevent modification
- **unlock_elements** — Unlock elements to allow modification
- **create_from_mermaid** — Convert a Mermaid diagram to Excalidraw elements and render them on the canvas
- **batch_create_elements** — Create multiple Excalidraw elements at once. For arrows, use startElementId/endElementId to bind arrows to shapes — Excalidraw auto-routes to element edges. Assign custom id to shapes so arrows can reference them.
- **get_element** — Get a single Excalidraw element by ID
- **clear_canvas** — Clear all elements from the canvas
- **export_scene** — Export the current canvas to .excalidraw JSON format. Optionally write to a file; a path ending in .md is written in the Obsidian Excalidraw plugin format (.excalidraw.md).
- **import_scene** — Import elements from a .excalidraw JSON file, an Obsidian .excalidraw.md file, or raw JSON data
- **export_to_image** — Export the current canvas to a PNG or SVG image. Renders headless in the canvas server (no browser tab needed); SVGs embed the fonts they use.
- **duplicate_elements** — Duplicate elements with a configurable offset
- **snapshot_scene** — Save a named snapshot of the current canvas state for later restoration
- **restore_snapshot** — Restore the canvas from a previously saved named snapshot
- **describe_scene** — Get an AI-readable description of the current canvas: element types, positions, connections, labels, spatial layout, and bounding box. Use this to understand what is on the canvas before making changes.
- **get_canvas_screenshot** — Render the current canvas to a PNG and return it as an image. Renders headless in the canvas server (no browser tab needed). Use this to visually verify what the diagram looks like.
- **read_diagram_guide** — Returns a comprehensive design guide for creating beautiful Excalidraw diagrams: color palette, sizing rules, layout patterns, arrow binding best practices, diagram templates, and anti-patterns. Call this before creating diagrams to produce professional results.
- **export_to_excalidraw_url** — Export the current canvas to a shareable excalidraw.com URL. The diagram is encrypted and uploaded; anyone with the URL can view it. Returns the shareable link.
- **set_viewport** — Control the canvas viewport (camera). Auto-fit all elements, zoom-to-fit a subset of elements, center on a specific element, or set zoom/scroll directly. Requires the canvas frontend open in a browser.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "mcp-excalidraw-server": {
    "command": "npx",
    "args": ["-y","mcp-excalidraw-server"]
  }
}
```

## Documentation

## What mcp-excalidraw-server does

mcp-excalidraw-server gives an AI agent control of an editable Excalidraw workspace. The agent can work with individual shapes, text, arrows, groups, frames, and other scene elements instead of regenerating an entire diagram for every change. It can also inspect the canvas through structured descriptions and rendered screenshots, making it possible to identify overlaps, misplaced labels, or incorrect connections before continuing.

The project exposes the canvas through three entry points: an MCP server for compatible clients, a command-line interface, and a REST API for custom applications or frameworks. These interfaces operate on the same local canvas server, which provides the Excalidraw web UI, REST endpoints, and WebSocket synchronization.

## How it works

Canvas-driving commands and the MCP process can start the local canvas automatically when it is not already running. The default canvas address is `http://127.0.0.1:3000`. MCP communication uses stdio, allowing a compatible client to launch the server as a local process.

Element operations cover the full editing cycle: creation, lookup, filtering, updates, deletion, duplication, grouping, alignment, distribution, and locking. Arrows can reference element IDs so they bind to shapes and route to their edges. Batch creation is available for diagrams that need many elements in one operation.

For visual verification, headless rendering produces PNG or SVG output without requiring an open browser tab. The server can also return a canvas screenshot to the agent. Scene descriptions provide element types, labels, positions, connections, spatial layout, and the overall bounding box in text form.

## Setup and configuration

Node.js 20 or newer is required. The package can be launched without a global installation using:

```bash
npx -y mcp-excalidraw-server <command>
```

Configure the MCP client to run the package as a stdio server. The CLI, MCP server, and REST-facing workflow share the automatically started canvas. Set `EXCALIDRAW_NO_AUTOSTART=1` when the canvas should not be started automatically.

Local drawing does not require an API key or account. Mermaid conversion runs in the local canvas environment. The canvas page loads Excalidraw fonts from the esm.sh CDN.

## Tools and capabilities

- Create, update, delete, query, duplicate, and retrieve individual elements.
- Create many elements in one call, including arrows bound to custom shape IDs.
- Group, ungroup, align, distribute, lock, and unlock elements.
- Convert Mermaid diagrams into editable Excalidraw content.
- Import `.excalidraw` JSON, Obsidian `.excalidraw.md`, or raw scene JSON.
- Export scenes to `.excalidraw` or Obsidian-compatible files, and render PNG or SVG images.
- Save named snapshots and restore earlier canvas states.
- Describe the scene, capture screenshots, read the diagram guide, and control the viewport.
- Produce an encrypted, shareable excalidraw.com URL.

## Limitations and notes

Viewport control requires the canvas frontend to be open in a browser. Sharing uploads the encrypted scene to excalidraw.com; anyone with the resulting URL can view it. The standard local workflow runs on Node.js, while image export and screenshots can use the server-side headless renderer without a browser tab. Multiple agents can operate on the same live canvas through its real-time synchronization layer.

_Full upstream README: https://allmcps.com/mcp/mcp-excalidraw-server/readme_