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