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 (
lockedflag)
- position (
- 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.
- Track and modify scene‑level state:
- Save Scene
Export the current scene (elements + appState) to a.excalidrawfile 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" }
- scene →
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"