# tldraw MCP Server

A full-featured [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that lets AI assistants like Claude create and edit [tldraw](https://tldraw.com) diagrams programmatically. With **30 tools** across 7 categories, it supports all 14 tldraw shape types and produces standard `.tldr` files.

## What is MCP?

The Model Context Protocol is an open standard that allows AI models to interact with external tools and services. This server exposes tldraw's drawing capabilities as MCP tools, enabling Claude (or any MCP-compatible client) to create complex diagrams, flowcharts, wireframes, and more — all through natural language.

## Features

- **14 shape types**: geo, text, arrow, note, frame, draw, line, image, video, bookmark, embed, highlight, and more
- **30 tools** organized into 7 categories
- **Rich text** support with tldraw's native format
- **Arrow bindings** — connect shapes with smart arrows
- **Full document lifecycle** — create, load, save, and export `.tldr` files
- **Zero browser dependencies** — pure Node.js, generates files directly

## Prerequisites

- **Node.js** 18+
- **npm** or compatible package manager
- An MCP-compatible client (Claude Code, Claude Desktop, etc.)

## Installation

```bash
git clone https://github.com/AndresMuelas2004/tldraw-mcp-server.git
cd tldraw-mcp-server
npm install
npm run build
```

## Configuration

### Claude Code

Add to your Claude Code MCP settings:

```json
{
  "mcpServers": {
    "tldraw": {
      "command": "node",
      "args": ["C:/path/to/tldraw-mcp-server/dist/index.js"]
    }
  }
}
```

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "tldraw": {
      "command": "node",
      "args": ["C:/path/to/tldraw-mcp-server/dist/index.js"]
    }
  }
}
```

Replace `C:/path/to/tldraw-mcp-server` with the actual path to the cloned repository.

## Available Tools

### Document Management
| Tool | Description |
|------|-------------|
| `tldraw_new_document` | Create a new empty document |
| `tldraw_load_document` | Load a `.tldr` file |
| `tldraw_save_document` | Save the current document |
| `tldraw_get_document_info` | Get document metadata |

### Shape Creation (14 types)
| Tool | Description |
|------|-------------|
| `tldraw_create_geo` | Geometric shapes (rectangle, ellipse, diamond, star, cloud, etc.) |
| `tldraw_create_text` | Text labels |
| `tldraw_create_arrow` | Arrows (with optional bindings) |
| `tldraw_create_note` | Sticky notes |
| `tldraw_create_frame` | Frames for grouping |
| `tldraw_create_draw` | Freehand drawings |
| `tldraw_create_line` | Multi-point lines |
| `tldraw_create_image` | Image shapes |
| `tldraw_create_video` | Video embeds |
| `tldraw_create_bookmark` | URL bookmarks |
| `tldraw_create_embed` | Embedded content |
| `tldraw_create_highlight` | Highlighter strokes |

### Connections
| Tool | Description |
|------|-------------|
| `tldraw_bind_arrow` | Bind arrow endpoints to shapes |
| `tldraw_unbind_arrow` | Remove arrow bindings |

### Shape Manipulation
| Tool | Description |
|------|-------------|
| `tldraw_move_shapes` | Move shapes to new coordinates |
| `tldraw_resize_shapes` | Resize shapes |
| `tldraw_rotate_shapes` | Rotate shapes |
| `tldraw_delete_shapes` | Delete shapes |
| `tldraw_duplicate_shapes` | Duplicate shapes |
| `tldraw_restyle_shapes` | Change shape styles |
| `tldraw_set_opacity` | Set shape opacity |
| `tldraw_update_shape_props` | Update any shape property |
| `tldraw_lock_shapes` | Lock/unlock shapes |

### Grouping & Ordering
| Tool | Description |
|------|-------------|
| `tldraw_group_shapes` | Group shapes together |
| `tldraw_ungroup_shapes` | Ungroup shapes |
| `tldraw_reparent_shapes` | Move shapes into frames/groups |
| `tldraw_reorder_shapes` | Change z-order (front/back) |

### Pages
| Tool | Description |
|------|-------------|
| `tldraw_create_page` | Create a new page |
| `tldraw_list_pages` | List all pages |
| `tldraw_rename_page` | Rename a page |
| `tldraw_delete_page` | Delete a page |
| `tldraw_reorder_page` | Reorder pages |

### Query & Camera
| Tool | Description |
|------|-------------|
| `tldraw_list_shapes` | List all shapes on a page |
| `tldraw_get_shape` | Get shape details by ID |
| `tldraw_list_bindings` | List all bindings |
| `tldraw_get_bindings_for_shape` | Get bindings for a specific shape |
| `tldraw_list_assets` | List all assets |
| `tldraw_set_camera` | Set camera position and zoom |

## Project Structure

```
tldraw-mcp-server/
├── src/
│   ├── index.ts              # Server entry point
│   ├── register-tools.ts     # Tool registration
│   ├── schemas/              # Zod schemas for shapes and styles
│   ├── state/                # Document state management
│   ├── tools/                # Tool implementations (one file per category)
│   └── utils/                # Helpers (IDs, indices, rich text, defaults)
├── examples/                 # Usage examples (diagram generation, serving)
├── dist/                     # Compiled output (generated)
├── package.json
└── tsconfig.json
```

## Examples

The `examples/` directory contains scripts that demonstrate usage:

- **`generate-diagram.mjs`** — Builds a complete multi-shape diagram programmatically
- **`serve-tldr.mjs`** — Serves a `.tldr` file over HTTP
- **`serve-html.mjs`** — Serves an HTML export of a diagram
- **`inject-diagram.mjs`** — Encodes a `.tldr` as base64 for browser injection
- **`prep-inject.mjs`** — Generates a Playwright-compatible inject function
- **`pw-inject.mjs`** — Full Playwright script for injecting diagrams into tldraw

```bash
# Build first
npm run build

# Generate a sample diagram
node examples/generate-diagram.mjs
```

## Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/my-feature`)
3. Commit your changes
4. Push to the branch and open a Pull Request

## License

[MIT](LICENSE)