home / mcp / excalidraw mcp server

Excalidraw MCP Server

Provides an Excalidraw canvas exposed via MCP for real-time diagramming and element CRUD from AI agents.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "yctimlin-mcp_excalidraw": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "EXPRESS_SERVER_URL=http://host.docker.internal:3000",
        "-e",
        "ENABLE_CANVAS_SYNC=true",
        "ghcr.io/yctimlin/mcp_excalidraw:latest"
      ],
      "env": {
        "ENABLE_CANVAS_SYNC": "true",
        "EXPRESS_SERVER_URL": "http://host.docker.internal:3000"
      }
    }
  }
}

You can run a live Excalidraw canvas and control it from AI agents using an MCP server and a dedicated agent skill. This setup lets you programmatically create, update, and export diagrams in real time, powered by the Model Context Protocol so your agents can interact with the canvas like a native service.

How to use

To use this MCP server, start the canvas server first and then launch the MCP server in stdio mode. Your agents connect through the MCP interface to issue commands that create and modify Excalidraw elements on the live canvas. The canvas is available locally at http://localhost:3000, and the MCP server updates the canvas in real time.

How to install

Prerequisites: Node.js (version 18 or newer) and npm installed on your machine.

npm ci
npm run build

Start the canvas server in one terminal window.

HOST=0.0.0.0 PORT=3000 npm run canvas

In a second terminal, run the MCP server in stdio mode so clients can connect to the canvas.

EXPRESS_SERVER_URL=http://localhost:3000 node dist/index.js

Additional configuration and usage notes

The MCP server can also be run from a Docker container if you prefer a contained environment. The container image exposes the same MCP interface and connects to the canvas via the canvas URL you provide.

Troubleshooting

If the canvas does not update, verify that EXPRESS_SERVER_URL points to the running canvas server and that ENABLE_CANVAS_SYNC is set to true when required by your setup.

Notes

The canvas server stores elements in memory. Restarting the canvas clears the current diagram. Use export/import workflows if you need persistence across restarts.

Troubleshooting and known pitfalls

Check that the canvas is running before attempting MCP connections. If batch operations fail to update or delete elements, ensure you are using a build that preserves element ids during batch creation.

Available tools

create_element

Create a new diagram element on the canvas with specified type and properties.

update_element

Update properties of an existing element by its id.

delete_element

Remove an element from the canvas by id.

query_elements

Search and retrieve elements that match given criteria.

get_resource

Retrieve current canvas state or specific resources.

batch_create_elements

Create multiple elements in a single operation while preserving IDs where supported.

align_elements

Align a set of elements according to a chosen alignment rule.

distribute_elements

Evenly distribute a group of elements across a chosen axis.

group_elements

Group multiple elements into a single composite.

ungroup_elements

Break apart a grouped element into its constituent parts.

create_from_mermaid

Convert Mermaid diagrams into Excalidraw elements on the canvas.