playbooks

Home / MCP / Excalidraw MCP Server

Excalidraw MCP Server

Provides an interactive Excalidraw canvas with MCP integration for real-time diagramming and AI-driven diagram creation.

typescript
475stars
View on GitHub
Installation
Add the following to your MCP client configuration file.

Configuration

View docs
{
    "mcpServers": {
        "excalidraw": {
            "command": "node",
            "args": [
                "/absolute/path/to/mcp_excalidraw/dist/index.js"
            ],
            "env": {
                "EXPRESS_SERVER_URL": "http://localhost:3000",
                "ENABLE_CANVAS_SYNC": "true",
                "LOG_FILE_PATH": "excalidraw.log",
                "DEBUG": "false",
                "PORT": "3000",
                "HOST": "localhost"
            }
        }
    }
}

You set up an Advanced Live Visual Diagramming system that connects an Excalidraw-based canvas with an MCP server so AI agents can create and manipulate diagrams in real time. The two components run separately but stay in sync, delivering a production-ready, browser-based canvas with robust MCP tooling for element creation, editing, and batching.

How to use

Open the live canvas in your browser at http://localhost:3000. Ensure the canvas server is running, and verify the connection status shows Connected. Your AI agents (such as Claude) can create and adjust diagram elements in real time, with changes appearing instantly on the canvas. Use the canvas controls, including the “Clear Canvas” action, to manage your workspace.

If you are integrating an MCP client, configure the MCP server to connect the AI agent to the canvas, so commands like creating rectangles, text, and arrows are reflected on the canvas. The system supports real-time WebSocket updates, multi-client synchronization, and batch operations for complex diagrams.

How to install

Prerequisites: you need Node.js (version 16+ recommended) and npm, or Docker if you prefer containerized runs.

Step 1. Set up the canvas server locally or with Docker.

# Local Canvas Server (example)
npm install
npm run build
npm run canvas

Step 2. Set up the MCP server as a local process or via Docker. You will run a process that connects to the canvas at http://localhost:3000 and enables real-time canvas synchronization.

# Local MCP server (example)
node dist/index.js

Configuration for MCP clients and IDEs

The MCP server is configured to run as a local process or via Docker. Use the following ready-to-run configurations to connect Claude Desktop, Claude Code, or Cursor IDE to the canvas. The configurations enable the canvas URL and real-time synchronization.

{
  "mcpServers": {
    "excalidraw": {
      "command": "node",
      "args": ["/absolute/path/to/mcp_excalidraw/dist/index.js"],
      "env": {
        "EXPRESS_SERVER_URL": "http://localhost:3000",
        "ENABLE_CANVAS_SYNC": "true"
      }
    }
  }
}

Troubleshooting and tips

If you encounter issues with the canvas not loading or elements not syncing, verify the canvas server is reachable at http://localhost:3000 and that EXPRESS_SERVER_URL points to the correct URL. Confirm ENABLE_CANVAS_SYNC is set to true in your MCP configuration, and check the browser console for WebSocket errors. For Docker users, ensure you use the --network host option to allow localhost access from the container.

Security and maintenance notes

Keep the canvas and MCP server updated to benefit from the latest stability improvements. Use strong access controls for any remote MCP endpoints and monitor logs to detect unusual activity. When using Docker, prefer official images and verify container network configurations to maintain secure isolation.

Additional notes

The system supports real-time collaboration with multiple clients connected to the same canvas. You can perform batch creation for complex diagrams, group and align elements, and apply locking to prevent accidental edits during critical steps.

Available tools

create_element

Create an Excalidraw element (rectangle, ellipse, diamond, text, etc.) with styling and positioning.

update_element

Modify an existing element by id, including position, size, and styling.

delete_element

Remove an element by id from the canvas.

query_elements

Search elements with filters such as type, position, or metadata.

batch_create_elements

Create multiple elements in a single operation for complex diagrams.

group_elements

Group multiple elements into a single logical unit.

unlock_elements

Unlock elements to allow editing again.

align_elements

Align a set of elements to a specified edge or center.