### Install and Build Project

Source: https://github.com/yctimlin/mcp_excalidraw/blob/main/README.md

Run these commands to install dependencies and build the project locally.

```bash
npm ci
npm run build
```

--------------------------------

### Local Setup for Excalidraw MCP Server

Source: https://context7.com/yctimlin/mcp_excalidraw/llms.txt

Install dependencies, build the project, and run the canvas and MCP servers locally. Ensure Node.js version is 18 or higher. The canvas server hosts the UI and API, while the MCP server connects to it.

```bash
# Prerequisites: Node >= 18
npm ci
npm run build

# Terminal 1 — canvas server (serves UI + REST API + WebSocket)
PORT=3000 npm run canvas
# Open http://127.0.0.1:3000 in a browser

# Terminal 2 — MCP server (stdio, connects to canvas)
EXPRESS_SERVER_URL=http://127.0.0.1:3000 node dist/index.js
```

--------------------------------

### Start Local Canvas Server

Source: https://github.com/yctimlin/mcp_excalidraw/blob/main/README.md

Start the Excalidraw canvas server on a specified port. Ensure network-level access controls are in place if exposing beyond localhost.

```bash
PORT=3000 npm run canvas
```

--------------------------------

### Install Excalidraw Skill for Claude Code (Project-level)

Source: https://github.com/yctimlin/mcp_excalidraw/blob/main/README.md

Instructions to install the Excalidraw skill for Claude Code at the project level, scoping it to a specific project.

```bash
mkdir -p /path/to/your/project/.claude/skills
cp -R skills/excalidraw-skill /path/to/your/project/.claude/skills/excalidraw-skill
```

--------------------------------

### Retrieve Built-in Diagram Design Guide

Source: https://context7.com/yctimlin/mcp_excalidraw/llms.txt

Returns the full diagram design guide, including canonical color palette, sizing rules, layout patterns, arrow binding best practices, diagram type templates, anti-patterns, and recommended drawing order.

```json
{
  "tool": "read_diagram_guide",
  "arguments": {}
}
```

--------------------------------

### Install Excalidraw Skill for Claude Code (User-level)

Source: https://github.com/yctimlin/mcp_excalidraw/blob/main/README.md

Instructions to install the Excalidraw skill for Claude Code at the user level, making it available across all projects.

```bash
mkdir -p ~/.claude/skills
cp -R skills/excalidraw-skill ~/.claude/skills/excalidraw-skill
```

--------------------------------

### Frontend Screenshots with agent-browser

Source: https://github.com/yctimlin/mcp_excalidraw/blob/main/README.md

Install agent-browser, open the canvas server URL, wait for network activity to cease, and take a screenshot.

```bash
agent-browser install
agent-browser open http://127.0.0.1:3000
agent-browser wait --load networkidle
agent-browser screenshot /tmp/canvas.png
```

--------------------------------

### Install Excalidraw Skill for Claude Code or Codex CLI

Source: https://context7.com/yctimlin/mcp_excalidraw/llms.txt

Instructions for installing the Excalidraw skill for Claude Code and Codex CLI by copying the skill directory to the respective user-level skills directories.

```bash
# Claude Code — user-level
mkdir -p ~/.claude/skills
cp -R skills/excalidraw-skill ~/.claude/skills/excalidraw-skill
# Invoke: /excalidraw-skill
```

```bash
# Codex CLI
mkdir -p ~/.codex/skills
cp -R skills/excalidraw-skill ~/.codex/skills/excalidraw-skill
```

--------------------------------

### Install Excalidraw Skill for Codex CLI

Source: https://github.com/yctimlin/mcp_excalidraw/blob/main/README.md

Commands to install the Excalidraw skill for the Codex CLI by copying the skill directory to the appropriate location.

```bash
mkdir -p ~/.codex/skills
cp -R skills/excalidraw-skill ~/.codex/skills/excalidraw-skill
```

--------------------------------

### read_diagram_guide

Source: https://context7.com/yctimlin/mcp_excalidraw/llms.txt

Retrieve the built-in design guide for Excalidraw, including color palettes, sizing rules, layout patterns, and best practices.

```APIDOC
## read_diagram_guide

### Description
Retrieve the built-in design guide for Excalidraw, including color palettes, sizing rules, layout patterns, best practices, and templates.

### Arguments
This operation takes no arguments.

### Request Example
```json
{
  "tool": "read_diagram_guide",
  "arguments": {}
}
```

### Response Example
Full markdown guide string including color tables, sizing rules, and templates.
Example excerpt:
| Blue   | #1971c2 | Primary actions, links |
| Light Blue | #a5d8ff | pairs with #1971c2    |
Minimum shape size: width >= 120px, height >= 60px
```

--------------------------------

### Docker Setup for Excalidraw MCP Server

Source: https://context7.com/yctimlin/mcp_excalidraw/llms.txt

Deploy the Excalidraw MCP canvas server using a Docker image or set up the full stack using Docker Compose. The canvas server is exposed on port 3000.

```bash
# Canvas server only
docker run -d -p 3000:3000 --name mcp-excalidraw-canvas \
  ghcr.io/yctimlin/mcp_excalidraw-canvas:latest

# Full stack (canvas + MCP) via Docker Compose
docker compose --profile full up
```

--------------------------------

### Get Snapshot by Name

Source: https://context7.com/yctimlin/mcp_excalidraw/llms.txt

Retrieves a specific snapshot by its name.

```APIDOC
## GET /api/snapshots/:name — Get snapshot by name

### Description
Retrieves a specific snapshot by its name.

### Method
GET

### Endpoint
/api/snapshots/:name

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the snapshot to retrieve.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **snapshot** (object) - The snapshot object containing its details.
```

--------------------------------

### REST API Mode: Create Elements and Arrows

Source: https://github.com/yctimlin/mcp_excalidraw/blob/main/skills/excalidraw-skill/SKILL.md

Use a `POST` request to `/api/elements/batch` to create elements and arrows. Labels are defined within a `label` object. Arrows are bound using `start` and `end` objects with element IDs.

```bash
curl -X POST http://127.0.0.1:3000/api/elements/batch \
  -H "Content-Type: application/json" \
  -d '{
    "elements": [
      {"id": "svc-a", "type": "rectangle", "x": 100, "y": 100, "width": 160, "height": 60, "label": {"text": "Service A"}},
      {"id": "svc-b", "type": "rectangle", "x": 400, "y": 100, "width": 160, "height": 60, "label": {"text": "Service B"}},
      {"type": "arrow", "x": 0, "y": 0, "start": {"id": "svc-a"}, "end": {"id": "svc-b"}, "label": {"text": "calls"}}
    ]
  }'
```

--------------------------------

### GET /api/elements

Source: https://context7.com/yctimlin/mcp_excalidraw/llms.txt

Lists all elements currently present on the canvas.

```APIDOC
## GET /api/elements — List all elements

### Description
Lists all elements currently present on the canvas.

### Method
GET

### Endpoint
`/api/elements`

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **elements** (array) - An array of element objects.
- **count** (integer) - The total number of elements returned.

### Request Example
```bash
curl http://127.0.0.1:3000/api/elements
```

### Response Example
```json
{"success":true,"elements":[...],"count":5}
```
```

--------------------------------

### Server-Side Arrow Routing Logic

Source: https://context7.com/yctimlin/mcp_excalidraw/llms.txt

Illustrates the internal server logic for `resolveArrowBindings`, which automatically computes precise start and end points for arrows connecting shapes, ensuring an 8px gap from the shape's edge.

```typescript
// Internal to server.ts — called automatically when arrows have start/end refs
// For rectangle "A" at (100,100,140,70) connecting to ellipse "B" at (350,100,140,70):
// Arrow start = right edge of A = {x: 240, y: 135}, gap=8 → finalStart.x = 248
// Arrow end = left edge of B = {x: 350, y: 135}, gap=8 → finalEnd.x = 342
// el.points = [[0,0],[94,0]]  (relative to start)
```

--------------------------------

### Batch Create Elements using REST API

Source: https://context7.com/yctimlin/mcp_excalidraw/llms.txt

Use this endpoint to create multiple elements on the canvas in a single request. It supports the REST `label`/`start`/`end` format, with arrow bindings resolved server-side.

```bash
curl -X POST http://127.0.0.1:3000/api/elements/batch \
  -H "Content-Type: application/json" \
  -d '{
    "elements": [
      { "id": "a", "type": "rectangle", "x": 100, "y": 100, "width": 140, "height": 70, "label": {"text": "Service A"} },
      { "id": "b", "type": "rectangle", "x": 350, "y": 100, "width": 140, "height": 70, "label": {"text": "Service B"} },
      { "type": "arrow", "x": 0, "y": 0, "start": {"id": "a"}, "end": {"id": "b"}, "label": {"text": "calls"} }
    ]
  }'
```

--------------------------------

### Get AI-Readable Canvas Description

Source: https://context7.com/yctimlin/mcp_excalidraw/llms.txt

Use `describe_scene` to obtain a structured text summary of all elements on the canvas, sorted by position. This is recommended before making changes to understand the current state.

```json
{
  "tool": "describe_scene",
  "arguments": {}
}
```

--------------------------------

### GET /api/sync/status

Source: https://context7.com/yctimlin/mcp_excalidraw/llms.txt

Retrieves memory usage and WebSocket statistics for the synchronization process.

```APIDOC
## GET /api/sync/status — Memory and WebSocket stats

### Description
Retrieves memory usage and WebSocket statistics for the synchronization process.

### Method
GET

### Endpoint
`/api/sync/status`

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **elementCount** (integer) - The total number of elements.
- **memoryUsage** (object) - An object containing memory usage details.
  - **heapUsed** (number) - Heap memory used in MB.
  - **heapTotal** (number) - Total heap memory in MB.
- **websocketClients** (integer) - The number of connected WebSocket clients.

### Request Example
```bash
curl http://127.0.0.1:3000/api/sync/status
```

### Response Example
```json
{"success":true,"elementCount":5,"memoryUsage":{"heapUsed":42,"heapTotal":64},"websocketClients":1}
```
```

--------------------------------

### Get Snapshot by Name using REST API

Source: https://context7.com/yctimlin/mcp_excalidraw/llms.txt

Fetches a specific snapshot by its name. The response includes the snapshot's name, elements, and creation timestamp.

```bash
curl http://127.0.0.1:3000/api/snapshots/v1-architecture
```

--------------------------------

### Arrow Routing: Curved Arrow Example

Source: https://github.com/yctimlin/mcp_excalidraw/blob/main/skills/excalidraw-skill/SKILL.md

Define a curved arrow using the `points` array for waypoints and `roundness` to control the curve's smoothness. Intermediate points lift the arrow over obstacles.

```json
{
  "type": "arrow", "x": 100, "y": 100,
  "points": [[0, 0], [50, -40], [200, 0]],
  "roundness": {"type": 2}
}
```

--------------------------------

### Configure Claude Desktop (Local Node)

Source: https://github.com/yctimlin/mcp_excalidraw/blob/main/README.md

JSON configuration for Claude Desktop to use a locally built MCP Excalidraw server via Node.js. Ensure the command path is absolute.

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

--------------------------------

### Run Local MCP Server (stdio)

Source: https://github.com/yctimlin/mcp_excalidraw/blob/main/README.md

Launch the MCP server locally, connecting to the canvas server via stdio. The EXPRESS_SERVER_URL environment variable should point to the canvas server.

```bash
EXPRESS_SERVER_URL=http://127.0.0.1:3000 node dist/index.js
```

--------------------------------

### MCP Inspector: List All Tools

Source: https://context7.com/yctimlin/mcp_excalidraw/llms.txt

Uses the MCP Inspector CLI to list all available tools, setting the Express server URL and enabling canvas synchronization.

```bash
# MCP Inspector — list all 26 tools
npx @modelcontextprotocol/inspector --cli \
  -e EXPRESS_SERVER_URL=http://127.0.0.1:3000 \
  -e ENABLE_CANVAS_SYNC=true -- \
  node dist/index.js --method tools/list
```

--------------------------------

### Development Commands

Source: https://github.com/yctimlin/mcp_excalidraw/blob/main/README.md

Run type checking and build commands for development.

```bash
npm run type-check
```

```bash
npm run build
```

--------------------------------

### GET /api/elements/:id

Source: https://context7.com/yctimlin/mcp_excalidraw/llms.txt

Retrieves a specific element from the canvas by its unique ID.

```APIDOC
## GET /api/elements/:id — Get element by ID

### Description
Retrieves a specific element from the canvas by its unique ID.

### Method
GET

### Endpoint
`/api/elements/:id`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the element to retrieve.

### Request Example
```bash
curl http://127.0.0.1:3000/api/elements/svc-api
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **element** (object) - The element object matching the provided ID.

### Response Example
```json
{"success":true,"element":{...}}
```
```

--------------------------------

### GET /api/elements/search

Source: https://context7.com/yctimlin/mcp_excalidraw/llms.txt

Queries elements on the canvas using various filters such as type, bounding box, and stroke style.

```APIDOC
## GET /api/elements/search — Query with filters

### Description
Queries elements on the canvas using various filters such as type, bounding box, and stroke style.

### Method
GET

### Endpoint
`/api/elements/search`

### Parameters
#### Query Parameters
- **type** (string) - Optional - Filters elements by their type (e.g., 'rectangle', 'arrow').
- **x_min** (number) - Optional - Minimum x-coordinate for bounding box filtering.
- **x_max** (number) - Optional - Maximum x-coordinate for bounding box filtering.
- **y_min** (number) - Optional - Minimum y-coordinate for bounding box filtering.
- **y_max** (number) - Optional - Maximum y-coordinate for bounding box filtering.
- **strokeStyle** (string) - Optional - Filters elements by their stroke style (e.g., 'dashed').

### Request Example (Filter by type)
```bash
curl "http://127.0.0.1:3000/api/elements/search?type=rectangle"
```

### Request Example (Filter by bounding box)
```bash
curl "http://127.0.0.1:3000/api/elements/search?x_min=0&x_max=400&y_min=0&y_max=300"
```

### Request Example (Combined filters)
```bash
curl "http://127.0.0.1:3000/api/elements/search?type=arrow&strokeStyle=dashed"
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **elements** (array) - An array of element objects matching the filters.
- **count** (integer) - The number of elements returned.

### Response Example
```json
{"success":true,"elements":[...],"count":2}
```
```

--------------------------------

### Configure Claude Desktop (Docker)

Source: https://github.com/yctimlin/mcp_excalidraw/blob/main/README.md

JSON configuration for Claude Desktop to use the MCP Excalidraw server running in Docker. It connects to the canvas server via `host.docker.internal`.

```json
{
  "mcpServers": {
    "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"
      ]
    }
  }
}
```

--------------------------------

### Get Element by ID - Canvas REST API

Source: https://context7.com/yctimlin/mcp_excalidraw/llms.txt

Retrieves a specific element from the Excalidraw canvas using its unique ID.

```bash
curl http://127.0.0.1:3000/api/elements/svc-api
```

--------------------------------

### MCP Smoke Test: List Tools

Source: https://github.com/yctimlin/mcp_excalidraw/blob/main/README.md

Use the MCP Inspector CLI to list available tools. Ensure EXPRESS_SERVER_URL and ENABLE_CANVAS_SYNC are set.

```bash
npx @modelcontextprotocol/inspector --cli \
  -e EXPRESS_SERVER_URL=http://127.0.0.1:3000 \
  -e ENABLE_CANVAS_SYNC=true -- \
  node dist/index.js --method tools/list
```

--------------------------------

### Add Files (Batch) using Files API

Source: https://context7.com/yctimlin/mcp_excalidraw/llms.txt

Adds multiple binary files to the server. Each file should be provided as an object with an ID, data URL, and MIME type.

```bash
curl -X POST http://127.0.0.1:3000/api/files \
  -H "Content-Type: application/json" \
  -d '[{"id":"file-1","dataURL":"data:image/png;base64,...","mimeType":"image/png"}]'
```

--------------------------------

### GET /health

Source: https://context7.com/yctimlin/mcp_excalidraw/llms.txt

Performs a health check on the canvas server. Returns status, timestamp, element count, and WebSocket client count.

```APIDOC
## GET /health — Health check

### Description
Performs a health check on the canvas server. Returns status, timestamp, element count, and WebSocket client count.

### Method
GET

### Endpoint
`/health`

### Response
#### Success Response (200)
- **status** (string) - The health status of the server.
- **timestamp** (string) - The current server timestamp.
- **elements_count** (integer) - The number of elements currently on the canvas.
- **websocket_clients** (integer) - The number of active WebSocket clients.

### Request Example
```bash
curl http://127.0.0.1:3000/health
```

### Response Example
```json
{"status":"healthy","timestamp":"2024-01-15T10:00:00.000Z","elements_count":5,"websocket_clients":1}
```
```

--------------------------------

### Workflow: Iterative Refinement (MCP)

Source: https://github.com/yctimlin/mcp_excalidraw/blob/main/skills/excalidraw-skill/SKILL.md

Illustrates an iterative refinement loop in MCP mode using `batch_create_elements`, `get_canvas_screenshot`, and `update_element` to visually verify and correct diagram issues.

```text
batch_create_elements
  → get_canvas_screenshot → "text truncated on auth-svc"
  → update_element (increase width) → get_canvas_screenshot → "overlap between auth-svc and rate-limiter"
  → update_element (reposition) → get_canvas_screenshot → "all checks pass"
  → proceed
```

--------------------------------

### Get Memory and WebSocket Stats - Canvas REST API

Source: https://context7.com/yctimlin/mcp_excalidraw/llms.txt

Retrieves memory usage and WebSocket client statistics from the Excalidraw canvas server.

```bash
curl http://127.0.0.1:3000/api/sync/status
```

--------------------------------

### Manage MCP Servers

Source: https://github.com/yctimlin/mcp_excalidraw/blob/main/README.md

CLI commands to list, add, or remove configured MCP servers.

```bash
claude mcp list              # List configured servers
claude mcp remove excalidraw # Remove a server
```

--------------------------------

### Get Canvas Screenshot

Source: https://github.com/yctimlin/mcp_excalidraw/blob/main/skills/excalidraw-skill/SKILL.md

Captures a screenshot of the current Excalidraw canvas. This is used to visually verify changes made to the diagram or to export the current state as an image.

```python
get_canvas_screenshot()
```

--------------------------------

### Import Scene

Source: https://context7.com/yctimlin/mcp_excalidraw/llms.txt

Import Excalidraw scene data from a file path or a JSON string. Supports replacing existing content or merging with it.

```APIDOC
## import_scene — Import a `.excalidraw` JSON file or raw JSON

`replace` mode clears the canvas first; `merge` mode appends to existing elements. Accepts a file path or raw JSON string.

### Import from file (Replace Mode)

#### Method
```json
{
  "tool": "import_scene",
  "arguments": {
    "filePath": "./diagrams/architecture.excalidraw",
    "mode": "replace"
  }
}
```

#### Response Example
```
"Imported 5 elements (mode: replace)\n\n✅ Synced to canvas"
```

### Import from inline JSON (Merge Mode)

#### Method
```json
{
  "tool": "import_scene",
  "arguments": {
    "data": "{\"type\":\"excalidraw\",\"version\":2,\"elements\":[...]}",
    "mode": "merge"
  }
}
```
```

--------------------------------

### Get Element

Source: https://github.com/yctimlin/mcp_excalidraw/blob/main/skills/excalidraw-skill/SKILL.md

Retrieves details of a specific element by its ID. This is useful for verifying an element's existence, checking its properties, or confirming it's not locked before performing operations.

```python
get_element(elementId='some_element_id')
```

--------------------------------

### Run Docker Canvas Server

Source: https://github.com/yctimlin/mcp_excalidraw/blob/main/README.md

Deploy the Excalidraw canvas server as a Docker container. This command maps port 3000 from the container to the host.

```bash
docker run -d -p 3000:3000 --name mcp-excalidraw-canvas ghcr.io/yctimlin/mcp_excalidraw-canvas:latest
```

--------------------------------

### Arrow Routing: Elbowed Arrow Example

Source: https://github.com/yctimlin/mcp_excalidraw/blob/main/skills/excalidraw-skill/SKILL.md

Create an elbowed (L-shaped) arrow by defining waypoints in the `points` array and setting the `elbowed` property to `true`. This is useful for cross-lane connections.

```json
{
  "type": "arrow", "x": 100, "y": 100,
  "points": [[0, 0], [0, -50], [200, -50], [200, 0]],
  "elbowed": true
}
```

--------------------------------

### List All Files using Files API

Source: https://context7.com/yctimlin/mcp_excalidraw/llms.txt

Retrieves a list of all binary files (e.g., images) managed by the API. The output includes file IDs, data URLs, MIME types, and creation timestamps.

```bash
curl http://127.0.0.1:3000/api/files
```

--------------------------------

### Configure OpenCode Local Node MCP Server

Source: https://github.com/yctimlin/mcp_excalidraw/blob/main/README.md

JSON configuration for OpenCode to connect to a local Node.js Excalidraw MCP server. Specify the command and environment variables.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "excalidraw": {
      "type": "local",
      "command": ["node", "/absolute/path/to/mcp_excalidraw/dist/index.js"],
      "enabled": true,
      "environment": {
        "EXPRESS_SERVER_URL": "http://127.0.0.1:3000",
        "ENABLE_CANVAS_SYNC": "true"
      }
    }
  }
}
```

--------------------------------

### MCP Smoke Test: Create Element

Source: https://github.com/yctimlin/mcp_excalidraw/blob/main/README.md

Use the MCP Inspector CLI to call the 'create_element' tool. Ensure EXPRESS_SERVER_URL and ENABLE_CANVAS_SYNC are set.

```bash
npx @modelcontextprotocol/inspector --cli \
  -e EXPRESS_SERVER_URL=http://127.0.0.1:3000 \
  -e ENABLE_CANVAS_SYNC=true -- \
  node dist/index.js --method tools/call --tool-name create_element \
  --tool-arg type=rectangle --tool-arg x=100 --tool-arg y=100 \
  --tool-arg width=300 --tool-arg height=200
```

--------------------------------

### Claude Desktop MCP Server Configuration

Source: https://context7.com/yctimlin/mcp_excalidraw/llms.txt

Configure Claude Desktop to use the Excalidraw MCP server by specifying the command, arguments, and environment variables in the `claude_desktop_config.json` file. Ensure the path to the `index.js` is absolute.

```json
// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "excalidraw": {
      "command": "node",
      "args": ["/absolute/path/to/mcp_excalidraw/dist/index.js"],
      "env": {
        "EXPRESS_SERVER_URL": "http://127.0.0.1:3000",
        "ENABLE_CANVAS_SYNC": "true"
      }
    }
  }
}
```

--------------------------------

### Cursor/OpenCode/Codex CLI MCP Server Configuration

Source: https://context7.com/yctimlin/mcp_excalidraw/llms.txt

Configure Excalidraw MCP server for Cursor, OpenCode, or Codex CLI by creating or updating the respective MCP configuration file (`.cursor/mcp.json`, etc.). Specify the Node.js command, arguments, and environment variables.

```json
// .cursor/mcp.json  (or opencode.json / codex mcp add)
{
  "mcpServers": {
    "excalidraw": {
      "command": "node",
      "args": ["/absolute/path/to/mcp_excalidraw/dist/index.js"],
      "env": {
        "EXPRESS_SERVER_URL": "http://127.0.0.1:3000",
        "ENABLE_CANVAS_SYNC": "true"
      }
    }
  }
}
```

--------------------------------

### Add MCP Server to Claude Code (Local Node, Project-level)

Source: https://github.com/yctimlin/mcp_excalidraw/blob/main/README.md

Command to add the local Node.js MCP Excalidraw server configuration to Claude Code for project-level scope, shared via a `.mcp.json` file.

```bash
claude mcp add excalidraw --scope project \
  -e EXPRESS_SERVER_URL=http://127.0.0.1:3000 \
  -e ENABLE_CANVAS_SYNC=true \
  -- node /absolute/path/to/mcp_excalidraw/dist/index.js
```

--------------------------------

### Register Local Node MCP Server with Codex CLI

Source: https://github.com/yctimlin/mcp_excalidraw/blob/main/README.md

Use this command to register a local Node.js Excalidraw MCP server with the Codex CLI. Environment variables and the command path are specified.

```bash
codex mcp add excalidraw \
  --env EXPRESS_SERVER_URL=http://127.0.0.1:3000 \
  --env ENABLE_CANVAS_SYNC=true \
  -- node /absolute/path/to/mcp_excalidraw/dist/index.js
```

--------------------------------

### Files API - List all files

Source: https://context7.com/yctimlin/mcp_excalidraw/llms.txt

Lists all binary files (image elements) managed by the API.

```APIDOC
## GET /api/files — List all files

### Description
Lists all binary files (image elements) managed by the API.

### Method
GET

### Endpoint
/api/files

### Response
#### Success Response (200)
- **files** (object) - An object where keys are file IDs and values are file metadata.
```

--------------------------------

### Run Excalidraw Skill Scripts

Source: https://github.com/yctimlin/mcp_excalidraw/blob/main/README.md

Execute skill scripts for health checks, exporting, and importing elements. Ensure EXPRESS_SERVER_URL is set or provide it via --url.

```bash
EXPRESS_SERVER_URL=http://127.0.0.1:3000 node skills/excalidraw-skill/scripts/healthcheck.cjs
```

```bash
EXPRESS_SERVER_URL=http://127.0.0.1:3000 node skills/excalidraw-skill/scripts/export-elements.cjs --out diagram.elements.json
```

```bash
EXPRESS_SERVER_URL=http://127.0.0.1:3000 node skills/excalidraw-skill/scripts/import-elements.cjs --in diagram.elements.json --mode batch
```

--------------------------------

### Workflow: Iterative Refinement (REST)

Source: https://github.com/yctimlin/mcp_excalidraw/blob/main/skills/excalidraw-skill/SKILL.md

Demonstrates an iterative refinement process in REST API mode, involving batch element creation, image export for evaluation, and element updates to fix issues.

```text
POST /api/elements/batch
  → POST /api/export/image → save PNG → evaluate
  → PUT /api/elements/:id (fix issues) → re-screenshot → evaluate
  → proceed
```

--------------------------------

### Import Elements via CLI

Source: https://github.com/yctimlin/mcp_excalidraw/blob/main/skills/excalidraw-skill/SKILL.md

Command to import Excalidraw elements from a JSON file using a Node.js script. Supports 'batch' or 'sync' import modes.

```bash
node scripts/import-elements.cjs --in diagram.elements.json --mode batch|sync
```

--------------------------------

### Outgoing Messages (Client to Server)

Source: https://context7.com/yctimlin/mcp_excalidraw/llms.txt

Demonstrates how the frontend posts export and viewport results back to the server via HTTP POST requests.

```bash
# Frontend posts export result back to HTTP
curl -X POST http://127.0.0.1:3000/api/export/image/result \
  -H "Content-Type: application/json" \
  -d '{ "requestId": "<id-from-ws-event>", "format": "png", "data": "<base64>" }'
```

```bash
# Frontend posts viewport result back
curl -X POST http://127.0.0.1:3000/api/viewport/result \
  -H "Content-Type: application/json" \
  -d '{ "requestId": "<id-from-ws-event>", "success": true, "message": "Viewport updated" }'
```

--------------------------------

### Configure OpenCode Docker MCP Server

Source: https://github.com/yctimlin/mcp_excalidraw/blob/main/README.md

This JSON configuration enables OpenCode to use the Excalidraw MCP server running in Docker. It defines the command to run the Docker container with necessary environment variables.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "excalidraw": {
      "type": "local",
      "command": ["docker", "run", "-i", "--rm", "-e", "EXPRESS_SERVER_URL=http://host.docker.internal:3000", "-e", "ENABLE_CANVAS_SYNC=true", "ghcr.io/yctimlin/mcp_excalidraw:latest"],
      "enabled": true
    }
  }
}
```

--------------------------------

### Import Canvas Scene

Source: https://context7.com/yctimlin/mcp_excalidraw/llms.txt

Imports scene data from a `.excalidraw` JSON file or a raw JSON string. The `mode` argument determines whether to replace existing elements or merge them.

```json
// Replace from file
{
  "tool": "import_scene",
  "arguments": {
    "filePath": "./diagrams/architecture.excalidraw",
    "mode": "replace"
  }
}
```

```json
// Merge from inline JSON
{
  "tool": "import_scene",
  "arguments": {
    "data": "{\"type\":\"excalidraw\",\"version\":2,\"elements\":[...]}",
    "mode": "merge"
  }
}
```

--------------------------------

### Import Scene

Source: https://github.com/yctimlin/mcp_excalidraw/blob/main/skills/excalidraw-skill/SKILL.md

Imports an Excalidraw scene from a file. The `mode` parameter can be set to 'replace' to overwrite the current scene or 'merge' to combine it with existing elements.

```python
import_scene(filePath='/path/to/load/diagram.excalidraw', mode='replace')
```

--------------------------------

### Generate Shareable Excalidraw URL

Source: https://context7.com/yctimlin/mcp_excalidraw/llms.txt

Fetches current elements, builds a complete Excalidraw scene, compresses it with zlib, encrypts it with AES-GCM-128, uploads the payload to https://json.excalidraw.com/api/v2/post/, and constructs a shareable URL with the decryption key embedded in the fragment.

```json
{
  "tool": "export_to_excalidraw_url",
  "arguments": {}
}
```

--------------------------------

### Manage MCP Servers with Codex CLI

Source: https://github.com/yctimlin/mcp_excalidraw/blob/main/README.md

Basic commands for managing registered MCP servers using the Codex CLI, including listing and removing servers.

```bash
codex mcp list              # List configured servers
```

```bash
codex mcp remove excalidraw # Remove a server
```

--------------------------------

### Retrieve Scene Metadata or Element List

Source: https://context7.com/yctimlin/mcp_excalidraw/llms.txt

Use `get_resource` to fetch either general scene metadata (theme, viewport, selections) or a list of all elements on the canvas.

```json
{
  "tool": "get_resource",
  "arguments": { "resource": "scene" }
}
```

```json
{
  "tool": "get_resource",
  "arguments": { "resource": "elements" }
}
```

--------------------------------

### Local Bind Regression Test

Source: https://github.com/yctimlin/mcp_excalidraw/blob/main/README.md

Run local bind regression tests using npm.

```bash
npm run test:bind
```

--------------------------------

### Add MCP Server to Claude Code (Local Node, User-level)

Source: https://github.com/yctimlin/mcp_excalidraw/blob/main/README.md

Command to add the local Node.js MCP Excalidraw server configuration to Claude Code for user-level scope. Requires specifying the absolute path to the script.

```bash
claude mcp add excalidraw --scope user \
  -e EXPRESS_SERVER_URL=http://127.0.0.1:3000 \
  -e ENABLE_CANVAS_SYNC=true \
  -- node /absolute/path/to/mcp_excalidraw/dist/index.js
```

--------------------------------

### MCP Inspector: Create Test Rectangle

Source: https://context7.com/yctimlin/mcp_excalidraw/llms.txt

Uses the MCP Inspector CLI to call the 'create_element' tool, specifying 'rectangle' as the type and defining its position and dimensions.

```bash
# MCP Inspector — create a test rectangle
npx @modelcontextprotocol/inspector --cli \
  -e EXPRESS_SERVER_URL=http://127.0.0.1:3000 \
  -e ENABLE_CANVAS_SYNC=true -- \
  node dist/index.js --method tools/call --tool-name create_element \
  --tool-arg type=rectangle --tool-arg x=100 --tool-arg y=100 \
  --tool-arg width=300 --tool-arg height=200
```

--------------------------------

### Batch Create Elements

Source: https://context7.com/yctimlin/mcp_excalidraw/llms.txt

Creates multiple elements on the canvas in a single request. Arrow bindings are resolved server-side.

```APIDOC
## POST /api/elements/batch — Batch create elements

### Description
Uses the REST `label`/`start`/`end` format. Arrow bindings are resolved server-side.

### Method
POST

### Endpoint
/api/elements/batch

### Request Body
- **elements** (array) - Required - An array of element objects to create.

### Request Example
```json
{
  "elements": [
    { "id": "a", "type": "rectangle", "x": 100, "y": 100, "width": 140, "height": 70, "label": {"text": "Service A"} },
    { "id": "b", "type": "rectangle", "x": 350, "y": 100, "width": 140, "height": 70, "label": {"text": "Service B"} },
    { "type": "arrow", "x": 0, "y": 0, "start": {"id": "a"}, "end": {"id": "b"}, "label": {"text": "calls"} }
  ]
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **elements** (array) - An array of the created elements.
- **count** (integer) - The number of elements created.
```

--------------------------------

### Skill Scripts

Source: https://github.com/yctimlin/mcp_excalidraw/blob/main/skills/excalidraw-skill/references/cheatsheet.md

Command-line scripts for interacting with Excalidraw functionalities. All scripts accept an optional `--url` argument to specify the canvas URL.

```APIDOC
## Skill Scripts

All scripts accept `--url <canvasUrl>` (defaults to `EXPRESS_SERVER_URL`).

### `healthcheck.cjs`
Runs a health check.

### `clear-canvas.cjs`
Clears the current canvas.

### `export-elements.cjs`
Exports canvas elements to a JSON file.

```bash
node scripts/export-elements.cjs --out diagram.elements.json
```

### `import-elements.cjs`
Imports canvas elements from a JSON file.

```bash
node scripts/import-elements.cjs --in diagram.elements.json --mode batch|sync
```

### `create-element.cjs`
Creates a new element on the canvas.

```bash
node scripts/create-element.cjs --data '{...}'
```

### `update-element.cjs`
Updates an existing element on the canvas.

```bash
node scripts/update-element.cjs --id <id> --data '{...}'
```

### `delete-element.cjs`
Deletes an element from the canvas.

```bash
node scripts/delete-element.cjs --id <id>
```
```

--------------------------------

### get_resource

Source: https://context7.com/yctimlin/mcp_excalidraw/llms.txt

Retrieves scene metadata (like theme, viewport, selections) or a list of all elements on the canvas.

```APIDOC
## get_resource

### Description
Retrieve scene metadata or element list.

### Method
GET

### Endpoint
/resources/{resource}

### Parameters
#### Path Parameters
- **resource** (string) - Required - The type of resource to retrieve. Options: 'scene' or 'elements'.

### Request Example
```json
// Get scene metadata (theme, viewport, selections)
{
  "tool": "get_resource",
  "arguments": { "resource": "scene" }
}
```

```json
// Get all elements
{
  "tool": "get_resource",
  "arguments": { "resource": "elements" }
}
```

### Response
#### Success Response (200)
- **scene** (object) - When resource is 'scene'. Contains theme, viewport, and selectedElements.
- **elements** (array) - When resource is 'elements'. Contains a list of all element objects.
```

--------------------------------

### Files API - Add files (batch)

Source: https://context7.com/yctimlin/mcp_excalidraw/llms.txt

Adds one or more binary files to the API.

```APIDOC
## POST /api/files — Add files (batch)

### Description
Adds one or more binary files (image elements) to the API.

### Method
POST

### Endpoint
/api/files

### Request Body
- **(array)** - Required - An array of file objects, each containing `id`, `dataURL`, and `mimeType`.

### Request Example
```json
[
  {"id":"file-1","dataURL":"data:image/png;base64,...","mimeType":"image/png"}
]
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **count** (integer) - The number of files added.
```

--------------------------------

### Agent CLI Scripts for Excalidraw

Source: https://context7.com/yctimlin/mcp_excalidraw/llms.txt

Provides Node.js CLI scripts for agents to interact with Excalidraw, including health checks, element import/export, creation, updates, deletion, and canvas clearing. These scripts default to using the EXPRESS_SERVER_URL.

```bash
# Health check
node skills/excalidraw-skill/scripts/healthcheck.cjs
# → prints JSON health response; exits 1 on failure
```

```bash
# Export all elements to JSON file
node skills/excalidraw-skill/scripts/export-elements.cjs --out diagram.elements.json
# → writes { exportedAt, expressServerUrl, elements: [...] }
```

```bash
# Import elements (append)
node skills/excalidraw-skill/scripts/import-elements.cjs \
  --in diagram.elements.json --mode batch
# mode: "batch" (append) or "sync" (clear + replace)
```

```bash
# Create an element
node skills/excalidraw-skill/scripts/create-element.cjs \
  --data '{"type":"rectangle","x":100,"y":100,"width":160,"height":80,"label":{"text":"My Box"}}'
```

```bash
# Update an element
node skills/excalidraw-skill/scripts/update-element.cjs \
  --id <element-id> \
  --data '{"backgroundColor":"#b2f2bb"}'
# Or from file: --file updates.json
```

```bash
# Delete an element
node skills/excalidraw-skill/scripts/delete-element.cjs --id <element-id>
```

```bash
# Clear all elements
node skills/excalidraw-skill/scripts/clear-canvas.cjs
# → logs "Cleared N elements"
```

--------------------------------

### List All Snapshots using REST API

Source: https://context7.com/yctimlin/mcp_excalidraw/llms.txt

Retrieves a list of all saved snapshots. Each snapshot entry includes its name, element count, and creation timestamp.

```bash
curl http://127.0.0.1:3000/api/snapshots
```

--------------------------------

### Register Docker MCP Server with Codex CLI

Source: https://github.com/yctimlin/mcp_excalidraw/blob/main/README.md

This command registers the Excalidraw MCP server running in Docker with the Codex CLI. It includes Docker run options and environment variables.

```bash
codex mcp add excalidraw \
  -- docker run -i --rm \
  -e EXPRESS_SERVER_URL=http://host.docker.internal:3000 \
  -e ENABLE_CANVAS_SYNC=true \
  ghcr.io/yctimlin/mcp_excalidraw:latest
```

--------------------------------

### Export to Excalidraw URL

Source: https://github.com/yctimlin/mcp_excalidraw/blob/main/skills/excalidraw-skill/SKILL.md

Generates a shareable URL for the current Excalidraw scene. The scene data is encrypted before generating the URL, making it suitable for sharing via excalidraw.com.

```python
export_to_excalidraw_url()
```

--------------------------------

### Frontend Screenshot with Agent Browser

Source: https://context7.com/yctimlin/mcp_excalidraw/llms.txt

Captures a screenshot of the frontend canvas using the 'agent-browser' tool. It opens the canvas URL, waits for network activity to settle, and then saves the screenshot to a specified file path.

```bash
# Frontend screenshot (agent-browser)
agent-browser open http://127.0.0.1:3000
agent-browser wait --load networkidle
agent-browser screenshot /tmp/canvas.png
```

--------------------------------

### List All Elements - Canvas REST API

Source: https://context7.com/yctimlin/mcp_excalidraw/llms.txt

Fetches a list of all elements currently present on the Excalidraw canvas.

```bash
curl http://127.0.0.1:3000/api/elements
```

--------------------------------

### batch_create_elements

Source: https://context7.com/yctimlin/mcp_excalidraw/llms.txt

Creates multiple elements atomically in a single HTTP request. It also resolves arrow bindings across the entire batch and allows assigning custom IDs to shapes for referencing.

```APIDOC
## batch_create_elements

### Description
Creates all elements in a single HTTP request and resolves arrow bindings across the entire batch. Assign custom `id` values to shapes so arrows in the same batch can reference them with `startElementId`/`endElementId`.

### Method
POST

### Endpoint
/elements/batch

### Request Body
- **elements** (array) - Required - An array of element objects to create.
  - **id** (string) - Optional - Custom ID for the element.
  - **type** (string) - Required - The type of the element (e.g., 'rectangle', 'arrow').
  - **x** (number) - Required - The x-coordinate of the element's top-left corner.
  - **y** (number) - Required - The y-coordinate of the element's top-left corner.
  - **width** (number) - Required - The width of the element.
  - **height** (number) - Required - The height of the element.
  - **text** (string) - Optional - Text content for the element.
  - **backgroundColor** (string) - Optional - Background color of the element.
  - **strokeColor** (string) - Optional - Stroke color of the element.
  - **startElementId** (string) - Optional - For arrows, the ID of the starting element.
  - **endElementId** (string) - Optional - For arrows, the ID of the ending element.
  - **strokeStyle** (string) - Optional - Stroke style for arrows (e.g., 'dashed').

### Request Example
```json
{
  "tool": "batch_create_elements",
  "arguments": {
    "elements": [
      { "id": "client", "type": "rectangle", "x": 60,  "y": 200, "width": 140, "height": 70, "text": "Client",   "backgroundColor": "#a5d8ff", "strokeColor": "#1971c2" },
      { "id": "server", "type": "rectangle", "x": 320, "y": 200, "width": 140, "height": 70, "text": "Server",   "backgroundColor": "#eebefa", "strokeColor": "#9c36b5" },
      { "id": "db",     "type": "ellipse",   "x": 580, "y": 200, "width": 140, "height": 70, "text": "Database", "backgroundColor": "#99e9f2", "strokeColor": "#0c8599" },
      { "id": "arr1", "type": "arrow", "x": 0, "y": 0, "startElementId": "client", "endElementId": "server", "text": "HTTP" },
      { "id": "arr2", "type": "arrow", "x": 0, "y": 0, "startElementId": "server", "endElementId": "db",     "text": "SQL", "strokeStyle": "dashed" }
    ]
  }
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the number of elements created.
- **elements** (array) - The created element objects.
- **status** (string) - Confirmation of sync status.
```

--------------------------------

### System API

Source: https://github.com/yctimlin/mcp_excalidraw/blob/main/skills/excalidraw-skill/references/cheatsheet.md

Endpoints for system health checks and status monitoring.

```APIDOC
## GET /health

### Description
Performs a health check on the system.

### Method
GET

### Endpoint
/health
```

```APIDOC
## GET /api/sync/status

### Description
Retrieves memory and WebSocket statistics.

### Method
GET

### Endpoint
/api/sync/status
```

--------------------------------

### Export Scene

Source: https://github.com/yctimlin/mcp_excalidraw/blob/main/skills/excalidraw-skill/SKILL.md

Exports the current Excalidraw scene to a file. An optional `filePath` can be provided to specify the output location for the `.excalidraw` file.

```python
export_scene(filePath='/path/to/save/diagram.excalidraw')
```

--------------------------------

### describe_scene

Source: https://context7.com/yctimlin/mcp_excalidraw/llms.txt

Generates an AI-readable description of the canvas, including element details, positions, and connections. Useful for understanding the canvas state before making changes.

```APIDOC
## describe_scene

### Description
Returns a structured text summary of all elements sorted top-to-bottom, left-to-right, including element IDs, types, positions, sizes, labels, colors, locks, groups, and arrow connections. Use this before making changes to understand the current canvas state.

### Method
GET

### Endpoint
/scene/description

### Response
#### Success Response (200)
- **description** (string) - A text-based description of the canvas scene.
```

--------------------------------

### Export Elements via CLI

Source: https://github.com/yctimlin/mcp_excalidraw/blob/main/skills/excalidraw-skill/SKILL.md

Command to export Excalidraw elements to a JSON file using a Node.js script. Specify the output file path with the `--out` flag.

```bash
node scripts/export-elements.cjs --out diagram.elements.json
```