Skip to main content
Glama
Excalidraw MCP Server

Excalidraw MCP Server

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.


Related MCP server: Excalidraw MCP Server

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"

Available Tools

12 tools
align_elementsC

Align elements to a specific position

Inputs: elementIds (required), alignment (required).

create_elementC

Create a new Excalidraw element

Inputs: type (required), x (required), y (required), width, +9 more.

delete_elementC

Delete an Excalidraw element

Inputs: id (required).

distribute_elementsD

Distribute elements evenly

Inputs: elementIds (required), direction (required).

get_resourceD

Get an Excalidraw resource

Inputs: resource (required).

group_elementsC

Group multiple elements together

Inputs: elementIds (required).

lock_elementsB

Lock elements to prevent modification

Inputs: elementIds (required).

query_elementsC

Query Excalidraw elements with optional filters

Inputs: type, filter.

save_sceneB

Saves the current Excalidraw elements and scene state to a .excalidraw file.

Inputs: filename.

ungroup_elementsB

Ungroup a group of elements

Inputs: groupId (required).

unlock_elementsB

Unlock elements to allow modification

Inputs: elementIds (required).

update_elementC

Update an existing Excalidraw element

Inputs: id (required), type, x, y, +10 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 12 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose targeting specific actions on Excalidraw elements or resources. There is no overlap between creation, deletion, updating, querying, grouping, locking, alignment, distribution, or file operations. The descriptions reinforce these distinct roles, making tool selection unambiguous.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern using snake_case (e.g., create_element, delete_element, group_elements). The naming convention is uniform throughout the set, with verbs clearly indicating actions and nouns specifying targets, making the tools predictable and easy to understand.

    Tool Count5/5

    With 12 tools, the server is well-scoped for managing Excalidraw diagrams, covering essential operations like CRUD for elements, grouping, locking, alignment, distribution, querying, and file saving. Each tool serves a distinct and necessary function, with no redundancy or excessive complexity.

    Completeness5/5

    The tool set provides complete coverage for the Excalidraw domain, including full CRUD lifecycle for elements (create, query, update, delete), grouping/ungrouping, locking/unlocking, alignment/distribution, and scene saving. There are no obvious gaps; agents can perform all core diagram editing and management tasks without dead ends.

    Related MCP Connectors

    Related MCP Servers