tldraw MCP Server

A full-featured Model Context Protocol (MCP) server that lets AI assistants like Claude create and edit tldraw 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

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:

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

Claude Desktop

Add to claude_desktop_config.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

# 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