tl-draw-mcp

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.

Related MCP server: Excalidraw MCP Server

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

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

Troubleshooting

MIT — see LICENSE.