# Excalidraw MCP Server

A Model Context Protocol server that provides full interaction with Excalidraw elements. This server enables LLMs to create, modify, query, and manipulate Excalidraw drawings through a structured API.

## Components

### Tools

* **create_element**
  * Create a new Excalidraw element
  * Required inputs: `type` (rectangle, ellipse, etc.), `x`, `y` coordinates
  * Optional inputs: dimensions, colors, styling properties

* **update_element**
  * Update an existing Excalidraw element by ID
  * Required input: `id` of the element to update
  * Optional inputs: any element property to modify

* **delete_element**
  * Delete an Excalidraw element
  * Required input: `id` of the element to delete

* **query_elements**
  * Query elements with optional filtering
  * Optional inputs: `type` to filter by element type, `filter` object with key-value pairs

* **get_resource**
  * Get a specific resource like scene information or all elements
  * Required input: `resource` type (scene, library, theme, elements)

* **group_elements**
  * Group multiple elements together
  * Required input: `elementIds` array of element IDs to group

* **ungroup_elements**
  * Ungroup a group of elements
  * Required input: `groupId` of the group to ungroup

* **align_elements**
  * Align multiple elements based on specified alignment
  * Required inputs: `elementIds` array and `alignment` (left, center, right, top, middle, bottom)

* **distribute_elements**
  * Distribute elements evenly
  * Required inputs: `elementIds` array and `direction` (horizontal or vertical)

* **lock_elements**
  * Lock elements to prevent modification
  * Required input: `elementIds` array of elements to lock

* **unlock_elements**
  * Unlock elements to allow modification
  * Required input: `elementIds` array of elements to unlock

## Usage with Claude Desktop

To use this server with the Claude Desktop app, add the following configuration to the "mcpServers" section of your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "excalidraw": {
      "command": "node",
      "args": ["src/index.js"],
      "env": {
        "LOG_LEVEL": "info",
        "DEBUG": "false"
      }
    }
  }
}
```

### Docker

```json
{
  "mcpServers": {
    "excalidraw": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "mcp/excalidraw"],
      "env": {
        "LOG_LEVEL": "info",
        "DEBUG": "false"
      }
    }
  }
}
```

## Installation

### NPM

```bash
# Install dependencies
npm install

# Start the server
npm start
```

### Docker

```bash
# Build the Docker image
docker build -t mcp/excalidraw .

# Run the container
docker run -i --rm mcp/excalidraw
```

## Environment Variables

The 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")

## Example Usage

Here are some examples of how to use the Excalidraw MCP server:

### Creating a Rectangle

```json
{
  "type": "rectangle",
  "x": 100,
  "y": 100,
  "width": 200,
  "height": 100,
  "backgroundColor": "#ffffff",
  "strokeColor": "#000000",
  "strokeWidth": 2,
  "roughness": 1
}
```

### Querying Elements

```json
{
  "type": "rectangle",
  "filter": {
    "strokeColor": "#000000"
  }
}
```

### Grouping Elements

```json
{
  "elementIds": ["elem1", "elem2", "elem3"]
}
```

## License

This MCP server is licensed under the MIT License. This means 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.