Which integrations are available for this server?

Provides tools for creating, reading, updating, and deleting tldraw shapes on a live canvas, enabling AI agents to draw diagrams, architecture charts, and flowcharts programmatically.

How do I use tldraw MCP Server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@tldraw MCP Server draw a flowchart of a login system" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

tldraw MCP Server

by Mihai-Codes

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

tldraw MCP Server

Programmatic canvas toolkit for AI agents — create, read, update, and delete tldraw shapes in real time via the Model Context Protocol.

Node.js TypeScript React tldraw MCP License: MIT

What It Is

An MCP server that gives AI agents (AdaL, Claude, Cursor, Codex CLI…) programmatic control over a live tldraw canvas. Draw diagrams, architecture charts, and flowcharts by just describing what you want.

Inspired by mcp_excalidraw — the same quality and completeness, built for the tldraw ecosystem.

Related MCP server: monosketch-mcp

Architecture

Flow: MCP client → MCP server (Zod validation) → Canvas server (Express HTTP) → WebSocket broadcast → Browser (tldraw editor, real time).

Quick Start

Prerequisites

Node.js >= 18

1 — Install & Build

git clone https://github.com/chindris-mihai-alexandru/tldraw-mcp-server.git
cd tldraw-mcp-server
npm install
npm run build
npm run build:frontend

2 — Start the Canvas Server

npm run canvas
# Canvas running at http://127.0.0.1:3000

Open http://127.0.0.1:3000 in your browser — this is the live canvas.

3 — Connect an MCP Client

The .mcp.json at the repo root works out-of-the-box for any project-level MCP client:

{
  "mcpServers": {
    "tldraw": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "EXPRESS_SERVER_URL": "http://127.0.0.1:3000"
      }
    }
  }
}

MCP Client Configuration

The default transport is stdio, so existing configs continue to work. Set MCP_TRANSPORT=http for shared HTTP endpoints (OpenAI Agents SDK, etc.).

Transport and adapter options

Variable	Default	Purpose
`MCP_TRANSPORT`	`stdio`	`stdio` for subprocess clients, `http` for Streamable HTTP
`MCP_CLIENT`	`generic`	Client hint: `adal`, `claude`, `cursor`, `openai`, `generic`
`MCP_SERVER_NAME`	`tldraw`	Server name for optional tool prefixes
`INCLUDE_SERVER_IN_TOOL_NAMES`	`false`	Expose tools as `tldraw__create_element`
`MCP_PERFORMANCE_MODE`	`false`	Compact tool descriptions to reduce discovery context
`MCP_HTTP_HOST`	`127.0.0.1`	HTTP bind host
`MCP_HTTP_PORT`	`3333`	HTTP bind port
`MCP_HTTP_PATH`	`/mcp`	Streamable HTTP MCP path
`MCP_ALLOWED_ORIGINS`	local origins	Comma-separated Origin allowlist
`MCP_ALLOWED_HOSTS`	local hosts	Comma-separated Host allowlist
`MCP_AUTH_TOKEN`	unset	Bearer-token auth for HTTP (set and send `Authorization: Bearer <token>`)

AdaL CLI

Project-level — the .mcp.json in this repo is pre-configured. Open AdaL in this directory and the server is auto-discovered.

cd tldraw-mcp-server
adal

Performance mode for lower discovery overhead:

{
  "mcpServers": {
    "tldraw": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "EXPRESS_SERVER_URL": "http://127.0.0.1:3000",
        "MCP_TRANSPORT": "stdio",
        "MCP_CLIENT": "adal",
        "MCP_PERFORMANCE_MODE": "true"
      }
    }
  }
}

Claude Code

# Project-level
claude mcp add tldraw --scope project \
  -e EXPRESS_SERVER_URL=http://127.0.0.1:3000 \
  -e MCP_TRANSPORT=stdio \
  -e MCP_CLIENT=claude \
  -- node /absolute/path/to/tldraw-mcp-server/dist/index.js

# User-level (available across all projects)
claude mcp add tldraw --scope user \
  -e EXPRESS_SERVER_URL=http://127.0.0.1:3000 \
  -e MCP_TRANSPORT=stdio \
  -e MCP_CLIENT=claude \
  -- node /absolute/path/to/tldraw-mcp-server/dist/index.js

Claude Desktop

Config: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

{
  "mcpServers": {
    "tldraw": {
      "command": "node",
      "args": ["/absolute/path/to/tldraw-mcp-server/dist/index.js"],
      "env": {
        "EXPRESS_SERVER_URL": "http://127.0.0.1:3000",
        "MCP_TRANSPORT": "stdio",
        "MCP_CLIENT": "claude"
      }
    }
  }
}

Cursor

Config: .cursor/mcp.json (project) or ~/.cursor/mcp.json (global)

{
  "mcpServers": {
    "tldraw": {
      "command": "node",
      "args": ["/absolute/path/to/tldraw-mcp-server/dist/index.js"],
      "env": {
        "EXPRESS_SERVER_URL": "http://127.0.0.1:3000",
        "MCP_TRANSPORT": "stdio",
        "MCP_CLIENT": "cursor"
      }
    }
  }
}

If a gateway expects server-prefixed tool names (tldraw__create_element), add "INCLUDE_SERVER_IN_TOOL_NAMES": "true" to the env.

OpenAI Agents SDK

Use Streamable HTTP for OpenAI Agents SDK and other shared-agent environments:

MCP_TRANSPORT=http \
MCP_HTTP_HOST=127.0.0.1 \
MCP_HTTP_PORT=3333 \
MCP_HTTP_PATH=/mcp \
EXPRESS_SERVER_URL=http://127.0.0.1:3000 \
MCP_CLIENT=openai \
node dist/index.js

import { Agent } from '@openai/agents'

const agent = new Agent({
  name: 'diagram-agent',
  instructions: 'Use the tldraw MCP server to create and inspect diagrams.',
  mcpServers: [
    {
      name: 'tldraw',
      url: 'http://127.0.0.1:3333/mcp',
      headers: process.env.MCP_AUTH_TOKEN
        ? { Authorization: `Bearer ${process.env.MCP_AUTH_TOKEN}` }
        : undefined,
    },
  ],
})

Codex CLI

codex mcp add tldraw \
  --env EXPRESS_SERVER_URL=http://127.0.0.1:3000 \
  --env MCP_TRANSPORT=stdio \
  -- node /absolute/path/to/tldraw-mcp-server/dist/index.js

Supergateway / systemd

Wrap the stdio server with supergateway for an HTTP endpoint:

npx -y supergateway \
  --stdio "node /opt/tldraw-mcp-server/dist/index.js" \
  --port 3333 \
  --baseUrl http://127.0.0.1:3333 \
  --ssePath /mcp \
  --messagePath /messages

Example systemd unit:

[Unit]
Description=tldraw MCP HTTP Gateway
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/tldraw-mcp-server
Environment=EXPRESS_SERVER_URL=http://127.0.0.1:3000
Environment=MCP_PERFORMANCE_MODE=true
ExecStart=/usr/bin/npx -y supergateway --stdio "node dist/index.js" --port 3333 --baseUrl http://127.0.0.1:3333 --ssePath /mcp --messagePath /messages
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Migration and rollback

No migration is required for existing AdaL users — stdio remains the default. To roll back optional behavior, unset MCP_TRANSPORT, MCP_PERFORMANCE_MODE, and INCLUDE_SERVER_IN_TOOL_NAMES, then use the original .mcp.json shape with only EXPRESS_SERVER_URL.

MCP Tools (27 tools)

Canvas Operations

Tool	Description
`create_element`	Create a shape, text, arrow, or note on the canvas
`get_element`	Get a single element by ID
`update_element`	Partially update any element property
`delete_element`	Delete an element by ID
`query_elements`	List/filter elements by type and bounding box
`batch_create_elements`	Create multiple elements atomically
`clear_canvas`	Remove all elements (requires `confirm: true`)

Grouping

Tool	Description
`group_elements`	Group 2+ elements — they move and transform as a unit
`ungroup_elements`	Dissolve a group, releasing all children as independent shapes

Sticky Notes

Tool	Description
`create_sticky`	Create a sticky note with sensible defaults (yellow, solid fill)
`update_sticky`	Update the content or styling of an existing sticky note
`list_sticky_templates`	Return pre-built sticky templates with recommended colors and use cases

Layout & Alignment

Tool	Description
`align_elements`	Align multiple elements left/center/right/top/middle/bottom
`distribute_elements`	Distribute elements evenly along horizontal or vertical axis
`auto_layout`	Automatically arrange using dagre, force-directed, or grid layout

Viewport & Scene

Tool	Description
`set_viewport`	Zoom, pan, zoom-to-fit, or center on a specific element
`read_diagram_guide`	Return color names, presets, and layout best practices
`describe_scene`	Summarize all canvas elements, positions, labels, and connections
`export_scene`	Export all elements as a JSON snapshot
`import_scene`	Import a JSON scene in replace or merge mode
`snapshot_scene`	Save the current canvas as a named in-memory snapshot
`restore_snapshot`	Restore a previously saved named snapshot

Export

Tool	Description
`get_canvas_screenshot`	Capture PNG from the canvas (server-side via Playwright, no browser needed)
`export_svg`	Export canvas as an SVG string
`export_png`	Export canvas as a PNG image (server-side Playwright)
`export_jpg`	Export canvas as a JPEG image (server-side Playwright)
`export_pdf`	Export canvas as a PDF (Playwright for full fidelity, pdf-lib fallback)

Shape Types

rectangle · ellipse · diamond · triangle · text · arrow · line · note · frame · star · cloud · hexagon

Element Properties

Property	Values	Default
`color`	`black` · `grey` · `blue` · `light-blue` · `violet` · `light-violet` · `red` · `light-red` · `orange` · `yellow` · `green` · `light-green` · `white`	`black`
`fill`	`none` · `semi` · `solid` · `pattern`	`none`
`dash`	`draw` · `solid` · `dashed` · `dotted`	`draw`
`size`	`s` · `m` · `l` · `xl`	`m`
`font`	`draw` · `sans` · `serif` · `mono`	`draw`

Development

# Type check
npm run type-check

# Backend (watch mode)
npm run dev:canvas   # canvas server on :3000
npm run dev          # MCP server on stdio

# Frontend (watch mode with hot reload)
npm run dev:frontend # Vite dev server on :5173

# Build everything
npm run build:all

# Run the full test suite once
npm test -- --run

Testing a Tool

# Create a rectangle
npx @modelcontextprotocol/inspector --cli \
  -e EXPRESS_SERVER_URL=http://127.0.0.1:3000 \
  -- node dist/index.js --method tools/call \
  --tool-name create_element \
  --tool-arg type=rectangle --tool-arg x=100 --tool-arg y=100 \
  --tool-arg width=200 --tool-arg height=80 \
  --tool-arg text="Hello" --tool-arg color=blue --tool-arg fill=semi

# List all tools
npx @modelcontextprotocol/inspector --cli \
  -e EXPRESS_SERVER_URL=http://127.0.0.1:3000 \
  -- node dist/index.js --method tools/list

Troubleshooting

Screenshot tool fails with "empty data"

get_canvas_screenshot prefers a server-side render (SVG + Playwright, no browser required). If Playwright is not installed or the export fails for any reason, it falls back to browser-based rendering. To ensure screenshots always work:

# Install Playwright (one-time)
npm install playwright
npx playwright install chromium

If the error persists even with Playwright installed, ensure the canvas server is running (npm run canvas) and try again.

License

MIT

Acknowledgments

tldraw — The infinite canvas SDK
mcp_excalidraw — Reference architecture
Model Context Protocol — Open standard for AI tool integration

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

cnvs.app A
app.cnvs
Real-time collaborative whiteboard — AI agents and humans edit the same board live over MCP.
Design Tools App Automation
2521
CodePic A
io.github.abelce
AI agent draws editable hand-drawn diagrams (flowchart, ER, architecture) via MCP, not static images
Software Architecture Design Tools
721
Flato Design MCPOAuth
io.github.sologovision
Connect AI agents to Flato's editable canvas runtime through a hosted MCP server.
Design Tools Developer Tools
22
Flowgraf A
in.flowgraf
Create and edit architecture diagrams from your AI agent; get an SVG and a live editable canvas.
Software Architecture Design Tools
32

Related MCP Servers

tldraw-mcp
App Automation Software Architecture Developer Tools
dpunj
A
license
A
quality
D
maintenance
A minimal MCP server for AI-driven canvas manipulation and visualization using tldraw. It enables AI clients to programmatically create, update, and manage shapes, flowcharts, and frames on a live interactive canvas.
Updated 7 months ago (2026-02-02 05:49 UTC)
9
1
MIT
monosketch-mcp
Software Architecture Design Tools
supersterling
F
license
Not graded
quality
C
maintenance
An MCP server that enables AI agents to create beautiful ASCII diagrams using Unicode box-drawing characters, with support for stateful canvas operations, multiple shape types, and style customization.
Updated 7 months ago (2026-02-13 21:45 UTC)
2
-
tldraw MCP Server
Design Tools Software Architecture
AndresMuelas2004
A
license
A
quality
D
maintenance
A full-featured MCP server that lets AI assistants create and edit tldraw diagrams programmatically with 30 tools across all 14 shape types.
Updated 6 months ago (2026-03-18 19:43 UTC)
43
2
MIT
obsidian-excalidraw-universal
Note Taking Design Tools
azgem102-max
F
license
Not graded
quality
B
maintenance
MCP server enabling AI assistants to read and write Obsidian notes, create and edit Excalidraw drawings, and run Excalidraw scripts via natural language commands.
Updated a month ago (2026-08-05 11:12 UTC)
-

tldraw MCP Server

What It Is

Architecture

Quick Start

Prerequisites

1 — Install & Build

2 — Start the Canvas Server

3 — Connect an MCP Client

MCP Client Configuration

Transport and adapter options

AdaL CLI

Claude Code

Claude Desktop

Cursor

OpenAI Agents SDK

Codex CLI

Supergateway / systemd

Migration and rollback

MCP Tools (27 tools)

Canvas Operations

Grouping

Sticky Notes

Layout & Alignment

Viewport & Scene

Export

Shape Types

Element Properties

Development

Testing a Tool

Troubleshooting

Screenshot tool fails with "empty data"

License

Acknowledgments

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

tldraw-mcp

monosketch-mcp

tldraw MCP Server

obsidian-excalidraw-universal