tldraw-mcp

Minimal MCP server for AI-driven canvas manipulation with tldraw.

Architecture

┌─────────────┐     stdio      ┌─────────────┐    WebSocket    ┌─────────────┐
│  AI Client  │◄──────────────►│  tldraw-mcp │◄───────────────►│   Widget    │
│ (Claude,etc)│                │   (server)  │   :4000         │  (tldraw)   │
└─────────────┘                └─────────────┘                 └─────────────┘
                                                                    :3000

Tools

Tool	Description
create_shape	Create shapes (rectangle, ellipse, star, cloud, diamond, etc.)
update_shape	Update shape properties (position, size, color, fill)
delete_shapes	Delete shapes by ID
connect_shapes	Connect two shapes with an arrow
create_frame	Create a frame to group shapes together
create_flowchart	Create a flowchart with nodes and edges (auto-layout)
get_snapshot	Get current canvas state
zoom_to_fit	Zoom canvas to fit all shapes
clear_canvas	Clear all shapes

Quick Start

# 1. Clone and install
git clone https://github.com/dpunj/tldraw-mcp
cd tldraw-mcp
bun install

# 2. Start the widget (tldraw canvas + WebSocket server)
cd widget
bun install
bun run dev
# Opens http://localhost:3000 (canvas) + ws://localhost:4000 (relay)

# 3. In another terminal, test the MCP server
cd ..
bun run dev

Claude Desktop Config

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "tldraw": {
      "command": "bun",
      "args": ["run", "/path/to/tldraw-mcp/src/index.ts"]
    }
  }
}

Environment Variables

Variable	Default	Description
TLDRAW_WS_URL	ws://localhost:4000	Widget WebSocket URL
WS_PORT	4000	Widget WS server port

Development

# MCP server
bun run dev      # Run server
bun run build    # Build for distribution
bun run check    # TypeScript check

# Widget
cd widget
bun run dev      # Start vite + WS server

License

MIT