📣 NEWS: Version 1.0.0 is now published to npm! You can run Excalidraw MCP directly using
npx excalidraw-mcpwithout installation. No setup required - just run and enjoy!
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.
You can run the Excalidraw MCP server directly using npx without installing anything:
npx excalidraw-mcpIf you prefer to install it globally:
npm install -g excalidraw-mcp
excalidraw-mcpThe following command-line options are available:
-d, --debug Enable debug logging
-?, --help Show this help message
Note: The following options are currently only fully functional in the Docker version:
-p, --port <port> Port to run the server on (default: 3000) -h, --host <host> Host to bind the server to (default: localhost) -m, --mode <mode> Transport mode: 'stdio' or 'http' (default: stdio)
Run with default options:
npx excalidraw-mcpEnable debug logging:
npx excalidraw-mcp --debug- Full Excalidraw Element Control: Create, update, delete, and query any Excalidraw element
- Advanced Element Manipulation: Group, align, distribute, lock, and unlock elements
- Resource Management: Access and modify scene information, libraries, themes, and elements
- Easy Integration: Works with Claude Desktop and other LLM platforms
- Docker Support: Simple deployment with containerization options
-
create_element
- Create a new Excalidraw element (rectangle, ellipse, diamond, etc.)
- Required inputs:
type,x,ycoordinates - Optional inputs: dimensions, colors, styling properties
-
update_element
- Update an existing Excalidraw element by ID
- Required input:
idof the element to update - Optional inputs: any element property to modify
-
delete_element
- Delete an Excalidraw element
- Required input:
idof the element to delete
-
query_elements
- Query elements with optional filtering
- Optional inputs:
typeto filter by element type,filterobject with key-value pairs
- get_resource
- Get a specific resource like scene information or all elements
- Required input:
resourcetype (scene, library, theme, elements)
-
group_elements
- Group multiple elements together
- Required input:
elementIdsarray of element IDs to group
-
ungroup_elements
- Ungroup a group of elements
- Required input:
groupIdof the group to ungroup
-
align_elements
- Align multiple elements based on specified alignment
- Required inputs:
elementIdsarray andalignment(left, center, right, top, middle, bottom)
-
distribute_elements
- Distribute elements evenly across space
- Required inputs:
elementIdsarray anddirection(horizontal or vertical)
-
lock_elements
- Lock elements to prevent modification
- Required input:
elementIdsarray of elements to lock
-
unlock_elements
- Unlock elements to allow modification
- Required input:
elementIdsarray of elements to unlock
To use this server with the Claude Desktop application, add the following configuration to the "mcpServers" section of your claude_desktop_config.json:
{
"mcpServers": {
"mcp_excalidraw": {
"command": "npx",
"args": ["-y", "excalidraw-mcp"]
}
}
}To use this server with the Cursor application, add the following configuration to the "mcpServers" section of your .cursor/mcp.json:
{
"mcpServers": {
"mcp_excalidraw": {
"command": "npx",
"args": ["-y", "excalidraw-mcp"]
}
}
}To use this server with Cursor, create a .cursor/mcp.json file in your workspace with the following configuration:
{
"mcpServers": {
"mcp_excalidraw": {
"command": "npx",
"args": ["-y", "excalidraw-mcp"]
}
}
}Make sure to:
- Replace
/path/to/your/directorywith the actual absolute path to your mcp_excalidraw installation - Create the
.cursordirectory if it doesn't exist - Ensure the path to
index.jsis correct and the file exists
{
"mcpServers": {
"excalidraw": {
"command": "docker",
"args": ["run", "-i", "--rm", "mcp/excalidraw"],
"env": {
"LOG_LEVEL": "info",
"DEBUG": "false"
}
}
}
}# Install globally
npm install -g excalidraw-mcp
# Run the server
excalidraw-mcp# Clone the repository
git clone <repository-url>
cd excalidraw-mcp
# Install dependencies
npm install
# Start the server
npm start# Build the Docker image
docker build -t mcp/excalidraw .
# Run the container
docker run -i --rm mcp/excalidrawThe server can be configured using the following environment variables:
LOG_LEVEL- Set the logging level (default: "info")DEBUG- Enable debug mode (default: "false")DEFAULT_THEME- Set the default theme (default: "light")
Here are some practical examples of how to use the Excalidraw MCP server:
{
"type": "rectangle",
"x": 100,
"y": 100,
"width": 200,
"height": 100,
"backgroundColor": "#ffffff",
"strokeColor": "#000000",
"strokeWidth": 2,
"roughness": 1
}{
"type": "rectangle",
"filter": {
"strokeColor": "#000000"
}
}{
"elementIds": ["elem1", "elem2", "elem3"]
}This Excalidraw MCP server is licensed under the MIT License. You are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.
Clone the repository and install dependencies:
git clone <repository-url>
cd excalidraw-mcp
npm installStart the development server:
npm run dev