@cuylabs/mcp-excalidraw

MCP (Model Context Protocol) server for Excalidraw diagram authoring. A thin adapter over @cuylabs/agent-excalidraw-toolkit that exposes 38 tools for creating, querying, mutating, and exporting Excalidraw diagrams. When --canvas is enabled, it serves the packaged browser preview from @cuylabs/agent-excalidraw-canvas-ui.

Architecture

┌──────────────┐  stdio  ┌──────────────────┐  imports  ┌─────────────────────────────┐
│  MCP Client  │ ──────> │  mcp-excalidraw  │ ───────>  │ agent-excalidraw-toolkit    │
│  (VS Code /  │ <────── │  server.ts       │ <──────── │ Session + tools + server    │
│   Claude)    │         │  tools.ts        │           │ schemas                     │
└──────────────┘         └──────────────────┘           └─────────────────────────────┘
                                │
                                │ --canvas serves static assets from
                                ▼
                         ┌─────────────────────────────┐
                         │ agent-excalidraw-canvas-ui  │
                         │ React + Excalidraw SPA      │
                         └─────────────────────────────┘

Thin Adapter Pattern: This package contains zero domain logic. Each MCP tool is a one-liner that validates params via Zod schema and delegates to the corresponding toolkit function.

Installation

pnpm add @cuylabs/mcp-excalidraw

Usage

As a standalone MCP server (stdio)

npx @cuylabs/mcp-excalidraw

With Canvas Server (real-time browser preview)

npx @cuylabs/mcp-excalidraw --canvas --port 3000

Then open http://localhost:3000 for a live Excalidraw preview that updates as tools execute.

The browser preview is bundled through @cuylabs/agent-excalidraw-canvas-ui. Users do not need to build frontend assets separately when installing from npm.

MCP client configuration

VS Code (.vscode/mcp.json):

{
  "servers": {
    "excalidraw": {
      "type": "stdio",
      "command": "npx",
      "args": ["@cuylabs/mcp-excalidraw"]
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "excalidraw": {
      "command": "npx",
      "args": ["@cuylabs/mcp-excalidraw"]
    }
  }
}

Programmatic usage

import { createServer } from "@cuylabs/mcp-excalidraw";

const { server, session } = createServer({
  name: "my-excalidraw-server",
  defaultSceneName: "main",
});

// Connect to your preferred transport
// server.connect(transport);

Available Tools (38)

| Category | Count | Tools | | ---------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Creation | 5 | create_shape, add_text, add_arrow, add_line, batch_create | | Mutation | 9 | update_element, delete_elements, set_style_properties, group_elements, ungroup_elements, set_lock, duplicate_element, batch_update, clear_canvas | | Query | 4 | get_scene, get_element, find_elements, summarise_scene | | Compound | 5 | create_labeled_shape, create_linear_layout, create_grid, create_connected_pair, create_icon_label | | File I/O | 2 | export_to_file, import_from_file | | Viewport | 3 | set_viewport, zoom_to_fit, zoom_to_element | | Layout | 4 | align_elements, distribute_elements, compute_position, get_group_bounds | | Session | 5 | list_scenes, create_scene, set_current_scene, get_current_scene, close_scene | | Screenshot | 1 | get_canvas_screenshot |

License

Apache 2.0