Tl Draw

An MCP server that draws on a live tldraw canvas from prompts. Works with Claude Code, Codex, and any other MCP client.

Open http://localhost:3030 in a browser and the agent's diagrams appear in real time.

create_diagram is the point. Describe a graph — nodes, edges, a direction — and the server measures every label, assigns layers, minimises edge crossings and binds the connectors to the nodes. It replaces reaching for mermaid, and unlike hand-placed coordinates the result is actually laid out.

---

1. Install

git clone <this repo> tl-draw-mcp
cd tl-draw-mcp
npm install
npm run build          # builds the web canvas, then the server

If npm reports a peer-dependency conflict, retry with npm install --legacy-peer-deps.

2. Wire it up

Claude Code

claude mcp add tldraw --scope user -- node /absolute/path/to/tl-draw-mcp/packages/server/dist/index.js

On Windows, use forward slashes in the path (or cmd /c node "D:/..."). Verify with claude mcp list, then restart Claude Code.

Install the skill so Claude knows when to draw:

# macOS / Linux
mkdir -p ~/.claude/skills && cp -r .claude/skills/tldraw ~/.claude/skills/

# Windows
xcopy /E /I .claude\skills\tldraw %USERPROFILE%\.claude\skills\tldraw

Codex

codex mcp add tldraw -- node /absolute/path/to/tl-draw-mcp/packages/server/dist/index.js

Or add it to ~/.codex/config.toml by hand — see examples/codex-config.toml:

[mcp_servers.tldraw]
command = "node"
args = ["/absolute/path/to/tl-draw-mcp/packages/server/dist/index.js"]

Codex has no skill mechanism, so the usage rules ship in the server's MCP instructions and in every tool description. For stronger steering, paste the short block at the end of docs/AGENT_GUIDE.md into your AGENTS.md.

Any other MCP client

It's a plain stdio MCP server: node /path/to/tl-draw-mcp/packages/server/dist/index.js. See examples/claude-code-config.json for the JSON form.

3. Use

1. Start your agent in any project.
2. The first tool call spins up the server — open http://localhost:3030.
3. The badge at the bottom-right reads tldraw MCP · connected.
4. Prompt: "Draw a flowchart of the login flow."

---

Tools

Tool	What it does
create_diagram	Node-and-edge diagram with automatic layout. Use this for any graph.
create_shape	Shapes at explicit positions — free-form drawing, wireframes, annotation.
connect_shapes	Bound connectors between shapes that already exist.
update_shape	Change position, size, colour or text by id.
delete_shape	Remove shapes by id, or { all: true } to clear.
get_canvas	Everything on the canvas, including how arrows are wired.

create_diagram

{
  "title": "Login flow",
  "direction": "down",        // down = mermaid TD, right = LR, also up / left
  "connector": "elbow",       // right-angled; "arc" for curved
  "nodes": [
    { "id": "start", "label": "Start", "role": "start" },
    { "id": "check", "label": "Credentials valid?", "role": "decision" },
    { "id": "home",  "label": "Go to dashboard", "role": "success" }
  ],
  "edges": [
    { "from": "start", "to": "check" },
    { "from": "check", "to": "home", "label": "yes" }
  ]
}

• Roles map meaning to conventional styling: process, start, end, decision, io, data, external, error, success, note.
• Nodes are sized to their label; no more text spilling out of boxes.
• Cycles are detected and bowed around the outside, so feedback loops don't cut back through the diagram.
• Re-running with the same node ids updates in place instead of duplicating.

Shape vocabulary

geo, text, arrow, line, draw, note, frame.

Link shapes by id, never by coordinates:

{ "type": "arrow", "from": "login", "to": "dashboard", "text": "on success" }

Bound arrows anchor on each shape's edge and re-route when either end moves.

Full reference: docs/AGENT_GUIDE.md.

---

Develop

npm test                                   # 59 unit tests
npm run test:e2e                           # drives a real browser (needs playwright)
npm run dev                                # stdio server + WS bridge on :3030
npm run dev --workspace @tldraw-mcp/web    # Vite HMR on :5173

The unit tests stop at the bridge — they prove the server sends the right payload, not that tldraw accepts it. Shape props, bindings and rich text are only validated by tldraw at runtime, so test:e2e drives an actual canvas in Chrome and asserts on what comes back. It skips cleanly if Playwright isn't installed (npm i -D playwright).

Layout

packages/server/src/layout.ts is a self-contained layered (Sugiyama-style) layout: break cycles → rank by longest path → reduce crossings with barycentre sweeps → assign coordinates with neighbour-pull and overlap separation. Pure functions, no tldraw types, so it's cheap to test.

packages/server/src/textMetrics.ts estimates label sizes from tldraw's own font constants — layout has to happen before any shape exists, so node sizes can't be measured in the browser.

Layout

packages/server   MCP stdio server, WS bridge, static host, layout, tool handlers
packages/web      Vite + React + tldraw browser app (builds into server/public)
.claude/skills/   SKILL.md for Claude Code
docs/             portable agent guide (Codex and other MCP clients)
e2e/              browser-driven end-to-end checks
examples/         MCP config for Claude Code and Codex

Configuration

Variable	Default	Meaning
TLDRAW_MCP_PORT	3030	Preferred port; falls back to 3031, 3032, … if taken.
TLDRAW_MCP_TIMEOUT_MS	20000	How long to wait for the browser to apply a batch.

Troubleshooting

Symptom	Fix
Agent says no canvas is connected	Open the URL from the error message. If a stale server holds :3030, the new one moves to :3031 — check the URL in the error.
tldraw validation error in the browser	Clear IndexedDB (DevTools → Application → IndexedDB → delete TLDRAW_*) and hard-refresh.
Badge says connected but nothing draws	Protocol mismatch after an upgrade — rebuild (npm run build) and hard-refresh the tab. The browser console names the versions.
Port :3030 busy	Automatic fallback to :3031 etc. The real URL is in the MCP logs (/mcp in Claude Code) and in every error message.
npm install peer-dep error	Retry with npm install --legacy-peer-deps.

---

MIT — see LICENSE.