Tldraw

io.github.tldrawPublished by GitHub account tldrawv0.1.0Updated Oct 25, 2026

Draw and visually collaborate with your agents on tldraw's canvas.

VerifiedStreamable HTTPWeb executableDeveloper ToolsMedia & Design

Overview

AI-generated overview

A remote tldraw canvas server that lets an assistant search the editor API and run JavaScript to draw and edit shapes on a shared canvas.

What you can do
Search the tldraw Editor API spec for methods, properties, categories and shape types by writing JavaScript against a spec object. Execute JavaScript against a live tldraw canvas, creating a new canvas when no canvasId is given. Persist and read canvas checkpoints, including saving shapes from user edits. App-only tools resolve pending exec requests and fetch the latest checkpoint for a canvas.
When to use it
Use it when you want an agent to draw, diagram or visually collaborate on a tldraw canvas inside an MCP client that supports the MCP app spec, rather than only producing text.
Requirements
A remote endpoint at the hosted Cloudflare Workers URL, or a local worker on localhost:8787 for development. The client must support the MCP app spec and render the canvas widget in an iframe. Local development needs Node.js with pnpm, the repo build, and for ChatGPT an HTTPS Cloudflare tunnel plus OpenAI org admin rights.
Before you install
The exec tool runs arbitrary JavaScript against the live editor, so code can create, change or delete canvas content. Canvas state is checkpointed to server-side SQLite storage and browser local storage, and sessions are destroyed after 7 days idle. Claude Desktop custom connectors may require a paid plan.

Installation

In SourceWeft

  1. Open Tldraw in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.tldraw%2Ftldraw/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "tldraw": {
      "type": "http",
      "url": "https://tldraw-mcp-app.tldraw.workers.dev/mcp"
    }
  }
}

README

tldraw MCP app

This is the tldraw MCP app. It exposes an interactive tldraw canvas to AI agents via the Model Context Protocol app specification, so you can work in tldraw with agents in any MCP client that supports the MCP app spec.

Architecture

The app has two parts: a server and a widget.

Server

The server runs in Cloudflare Workers via src/worker.ts, using a Durable Object (TldrawMCP) backed by SQLite for persistent checkpoint storage.

It exposes:

  • search — query the extracted Editor API spec in a sandboxed dynamic worker
  • exec — execute JavaScript against the live editor in the widget via a pending-request callback bridge
  • _exec_callback — app-only tool the widget calls to resolve a pending exec request
  • save_checkpoint / read_checkpoint — app-only tools used by the widget for checkpoint persistence

Widget

The widget is a React app (src/widget/mcp-app.tsx) that renders a full tldraw canvas inside the MCP host's iframe.

When the AI calls exec, the server creates a pending request and the widget picks it up, runs the code through a focused editor proxy (src/widget/focused/) that translates between an AI-friendly shape format (simple string IDs, flat _type shapes) and tldraw's internal TLShape/TLShapeId types, then calls _exec_callback to resolve the pending request with the result. Canvas state is checkpointed to the Durable Object's SQLite database and to the browser's local storage.

Developing

Prerequisites

The widget build depends on generated files (editor-api.json, method-map.json) that are extracted from the editor's TypeScript declarations. Before you can develop or build the mcp-app, you need to build the core packages first:

bash
# from the repo rootpnpm build

This produces the .tsbuild/ output that pnpm extract-api reads from. The build and dev scripts run extract-api automatically, so you don't need to call it separately.

Package scripts

Run all commands from apps/mcp-app.

CommandWhat it does
pnpm buildBuild the widget HTML
pnpm devBuild widget + start local Cloudflare worker (HTTP MCP on localhost:8787)
pnpm dev:tunnelBuild widget + start a stable named Cloudflare tunnel + local worker with WORKER_ORIGIN set to the tunnel URL
pnpm run deployBuild widget + deploy the Cloudflare worker to production

pnpm dev:tunnel requires the cloudflared CLI to be installed on your machine and a one-time cloudflared tunnel login. It serves a stable per-user hostname (<user>-mcp-app-dev.tldraw.xyz) via a named tunnel, so the URL you register in hosted MCP clients stays the same across runs instead of changing every time. The user slug defaults to whoami; override it (or the zone/port) with MCP_TUNNEL_USER, MCP_TUNNEL_ZONE, and PORT. The zone must be a Cloudflare-hosted zone (tldraw.xyz is; tldraw.dev/tldraw.com are on Vercel and won't work).

The worker defaults to production-safe behavior in wrangler.toml, including setting MCP_IS_DEV="false". Local HTTP dev scripts override that with MCP_IS_DEV=true so local Claude/ChatGPT connectors suppress ui.domain while production deployments keep it enabled.

Cursor setup

Add these two servers in ~/.cursor/mcp.json:

json
{	"mcpServers": {		"tldraw": {			"transport": "http",			"url": "https://tldraw-mcp-app.tldraw.workers.dev/mcp"		},		"tldraw-local": {			"command": "npx",			"args": ["-y", "mcp-remote", "http://127.0.0.1:8787/mcp"]		}	}}

Claude Desktop local setup

For local Claude Desktop development, use claude_desktop_config.json with the local HTTP server:

json
{	"mcpServers": {		"tldraw-local": {			"command": "npx",			"args": ["-y", "mcp-remote", "http://127.0.0.1:8787/mcp"]		}	}}

Claude Desktop remote setup

If you'd like to try the remote MCP server in Claude Desktop, use the in-app connector flow rather than adding the production URL to claude_desktop_config.json.

  1. Open Claude Desktop
  2. In the sidebar, go to Customize
  3. Open Connectors
  4. Click the button to add a connector, then choose Add custom connector
  5. Give it a name such as tldraw
  6. Paste https://tldraw-mcp-app.tldraw.workers.dev/mcp as the server URL

The Add custom connector option is not available on the free plan, so you may need Max or another paid plan.

If you need Notion access in Claude Desktop, use the Notion MCP connector for that separately.

ChatGPT local dev

ChatGPT requires an HTTPS origin, so you need a Cloudflare tunnel. You must be an admin of your OpenAI org/workspace to do local dev.

First-time setup (once per machine):

  1. Run cloudflared tunnel login and choose the tldraw.xyz zone

Then, each session:

  1. Run pnpm dev:tunnel in apps/mcp-app
  2. It serves your stable hostname, e.g. https://<user>-mcp-app-dev.tldraw.xyz (the first run also creates the named tunnel and its DNS route)
  3. In ChatGPT web (not the desktop app), go to Apps and add your app using that URL
  4. You can then test in both ChatGPT web and the desktop or mobile apps

Because the hostname is stable per user, you only add the app in ChatGPT once — subsequent pnpm dev:tunnel runs reuse the same URL.

dev:tunnel automatically wires WORKER_ORIGIN to the stable tunnel URL and sets MCP_IS_DEV=true for the local worker.

Iteration loop

  1. Make code changes in apps/mcp-app
  2. Run the relevant script (dev or dev:tunnel)
  3. Disconnect and reconnect the MCP server in your client (or reload the page/app)
  4. When making widget changes, make sure to rebuild, either by running pnpm build or rerunning any of the dev scripts.

Reconnecting the server after changes is the most reliable way to pick up new code, especially when the widget HTML changes.

Session storage lifecycle

Each MCP session is a TldrawMCP Durable Object. It keeps up to MAX_CHECKPOINTS (50) canvas snapshots and destroys itself after IDLE_TTL_MS (7 days) without a checkpoint save — a schedule armed in init() and re-armed on every check.

Contact

Find us on Twitter/X at @tldraw.

Community

Have questions, comments or feedback? Join our discord. For the latest news and release notes, visit tldraw.dev.

Source: apps/mcp-app/README.md at commit a0cd8f2

Tools

6

exec

Execute Code

Execute JavaScript code on a tldraw canvas. The code runs in the widget with access to the live `editor` instance, helper functions, and normal js. Use the `search` tool first to discover available Editor methods and shape types. Each canvas has a unique `canvasId`. Omit `canvasId` to create a new blank canvas. To edit an existing canvas, pass the `canvasId` that was returned by a previous exec call. Shapes and text grow depending on the amount of text they have. Use clever scripting to ensure there are no unintended overlaps. Examples: - Create a rectangle: editor.createShape({ _type: 'rectangle', shapeId: 'box1', x: 200, y: 120, w: 320, h: 180, text: 'Hello' }) - Connect shapes with an arrow: editor.createShape({ _type: 'arrow', shapeId: 'a1', fromId: 'box1', toId: 'box2', x1: 0, y1: 0, x2: 100, y2: 0 }) - Select and zoom: editor.select('box1'); editor.zoomToSelection() - Read shapes: return editor.getCurrentPageShapes() - Distribute evenly: editor.distributeShapes(editor.getSelectedShapeIds(), 'horizontal') - Box around shapes: boxShapes(['box1', 'box2'], { text: 'Group label', color: 'blue' }) - Stack shapes dynamically: editor.createShape({ _type: 'rectangle', shapeId: 'a', x: 0, y: 0, w: 300, h: 200, text: 'First box\nwith wrapping text' }); const bounds = editor.getShapePageBounds('a'); editor.createShape({ _type: 'rectangle', shapeId: 'b', x: 0, y: bounds.maxY + 20, w: 300, h: 200, text: 'Below first' })

ParameterscoderequiredcanvasId

_exec_callback

Exec Callback

App-only: widget calls this to resolve a pending exec request.

ParameterserrorresultchannelrequiredexecKey

_get_canvas_state

Get Canvas State

App-only: get the latest checkpoint for a canvas by its canvasId.

ParameterscanvasIdrequired

read_checkpoint

Read Checkpoint

App-only: read shapes from a checkpoint by ID.

ParameterscheckpointIdrequired

save_checkpoint

Save Checkpoint

App-only: save shapes to a checkpoint (from user edits). shapesJson and assetsJson must be JSON array strings.

ParameterscanvasIdassetsJsonshapesJsonrequiredbindingsJsoncheckpointIdrequired

Version history

1
  1. v0.1.0LatestSep 16, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

    Declare a license in the repository or the registry entry.