Excalidraw MCP Server: Powerful Drawing API for LLM Integration

A comprehensive Model Context Protocol (MCP) server that enables seamless interaction with Excalidraw diagrams and drawings. This server provides LLMs (Large Language Models) with the ability to create, modify, query, and manipulate Excalidraw drawings through a structured, developer‑friendly API.

Features

• Full Excalidraw Element Control
  Create, update, delete, and query any Excalidraw element (rectangle, ellipse, diamond, text, arrow, etc.), including support for:
  • position (x, y)
  • dimensions (width, height)
  • styling (backgroundColor, strokeColor, strokeWidth, roughness, opacity)
  • text (text, fontSize, fontFamily)
  • line geometry (points)
  • locking (locked flag)
• Advanced Element Manipulation
  Group, ungroup, align, distribute, lock, and unlock elements.
• Scene & AppState Management
  • Track and modify scene‑level state: theme, viewBackgroundColor, viewport (scroll & zoom), selectedElements, groups.
  • Retrieve library of all elements or individual scene properties.
• Save Scene
  Export the current scene (elements + appState) to a .excalidraw file on disk.
• Resource Management
  Access and modify scene information, element library, theme, and raw element data.
• Easy Integration
  Compatible with Claude Desktop, Cursor, and any other LLM platforms that support MCP.
• Docker Support
  Simple containerized deployment for zero‑dependency installs.

---

API Tools Reference

Element Creation and Modification

create_element

Create a new Excalidraw element.

• Input

  {
    "type": "<element type>",
    "x": <number>,
    "y": <number>,
    "width": <number, optional>,
    "height": <number, optional>,
    "points": [{"x":<number>,"y":<number>}…],
    "backgroundColor": "<hex>",
    "strokeColor": "<hex>",
    "strokeWidth": <number>,
    "roughness": <number>,
    "opacity": <0–1>,
    "text": "<string>",
    "fontSize": <number>,
    "fontFamily": "<string>",
    "locked": <boolean>
  }
  

• Output

  { "id": "<generated‑id>", "type": "<element type>", "created": true }
  

update_element

Update properties of an existing element.

• Input

  {
    "id": "<element id>",
  }
  

• Output

  { "id": "<element id>", "updated": true, "version": <new‑version‑number> }
  

delete_element

Remove an element from the scene.

• Input

  { "id": "<element id>" }
  

• Output

  { "id": "<element id>", "deleted": true }
  

query_elements

List elements matching optional filters.

• Input

  {
    "type": "<element type>",        
    "filter": { "<prop>": <value> }  
  }
  

• Output

  [ { /* element objects */ } … ]
  

Resource Management

get_resource

Retrieve scene or library information.

• Input

  { "resource": "scene"|"library"|"theme"|"elements" }
  

• Output
  • scene → { theme, viewport: {x,y,zoom}, selectedElements: […] }
  • library/elements → { elements: [ … ] }
  • theme → { theme: "light"|"dark" }

Element Organization

group_elements / ungroup_elements

Group or ungroup element collections.

• Input

  { "elementIds": ["id1","id2",…] }
  { "groupId": "<group id>" }
  

• Output

  { "groupId": "<new‑id>", "elementIds": […], "ungrouped": true? }
  

align_elements

Align multiple elements to specified edge or center.

• Input

  { "elementIds": […], "alignment": "left"|"center"|"right"|"top"|"middle"|"bottom" }
  

• Output
  { aligned: true, elementIds: […], alignment: "<alignment>" }

distribute_elements

Evenly space elements horizontally or vertically.

• Input

  { "elementIds": […], "direction": "horizontal"|"vertical" }
  

• Output
  { distributed: true, elementIds: […], direction: "<direction>" }

lock_elements / unlock_elements

Prevent or allow editing of elements.

• Input

  { "elementIds": [… ] }
  

• Output
  { locked: true|false, elementIds: […] }

Scene Management

save_scene

Export current scene (elements + appState) to a .excalidraw file.

• Input

  { "filename": "<optional, must end with .excalidraw>" }
  

• Output
  Scene saved successfully to <filename> or error message.

---

Integration Examples

Claude Desktop

"mcpServers": {
  "excalidraw": {
    "command": "node",
    "args": ["src/index.js"],
    "env": {
      "LOG_LEVEL": "info",
      "DEBUG": "false"
    }
  }
}

Cursor

Create .cursor/mcp.json:

{
  "mcpServers": {
    "excalidraw": {
      "command": "node",
      "args": ["/absolute/path/to/mcp_excalidraw/src/index.js"],
      "env": { "LOG_LEVEL": "info", "DEBUG": "false" }
    }
  }
}

Docker

docker run -i --rm mcp/excalidraw

Or in MCP config:

"mcpServers": {
  "excalidraw": {
    "command": "docker",
    "args": ["run", "-i", "--rm", "mcp/excalidraw"],
    "env": { "LOG_LEVEL": "info", "DEBUG": "false" }
  }
}

---

Installation Guide

# Install dependencies
npm install

# Run development server
npm start

Docker

docker build -t mcp/excalidraw .
docker run -i --rm mcp/excalidraw

---

Configuration Options

Set via environment variables in .env or your container:

• LOG_LEVEL — logging level (default: "info")
• DEBUG — debug mode ("true"/"false", default: "false")
• DEFAULT_THEME — default UI theme ("light"/"dark", default: "light")

---

Usage Examples

Create & Lock a Rectangle

{"type":"rectangle","x":50,"y":50,"width":100,"height":80,"backgroundColor":"#f3f3f3","strokeColor":"#333","locked":true}

{ "id":"abc123","type":"rectangle","created":true }

{"elementIds":["abc123"]}

Save Scene to File

{"filename":"my_drawing.excalidraw"}

"Scene saved successfully to my_drawing.excalidraw"