Skip to main content
Glama

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

Codex users can skip this step: the Codex plugin ships prebuilt.

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

Install the plugin. It bundles the MCP server, the canvas and the tldraw skill into one package, so there's nothing to clone or build. The only requirement is Node 20+ on your PATH.

codex plugin marketplace add Siddharth11Roy/tldraw-claude-mcp
codex plugin add tldraw@tldraw-mcp

Then restart Codex. The CLI and the desktop app share the same install.

Update

codex plugin marketplace upgrade tldraw-mcp && codex plugin add tldraw@tldraw-mcp

Uninstall

codex plugin remove tldraw@tldraw-mcp

Port or timeout

Export TLDRAW_MCP_PORT / TLDRAW_MCP_TIMEOUT_MS before starting Codex; the plugin passes them through.

From a clone, point Codex at the prebuilt bundle (no npm install needed):

codex mcp add tldraw -- node /absolute/path/to/tl-draw-mcp/plugins/tldraw/server/tldraw-mcp.mjs

Or edit ~/.codex/config.toml by hand; see examples/codex-config.toml. Use either the plugin or a manual entry, not both: they would register two servers both named tldraw.

A manual setup doesn't install the skill. The usage rules still reach Codex through the server's MCP instructions and the tool descriptions. 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                                   # 60 unit tests
npm run test:e2e                           # drives a real browser (needs playwright)
npm run test:plugin                        # runs the Codex plugin from a clean copy
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).

The Codex plugin is generated, and committed

Codex installs plugins straight from this repo with no build step, so plugins/tldraw/ holds build output:

  • server/tldraw-mcp.mjs: the server and its npm dependencies, bundled with esbuild.

  • public/: the canvas.

  • skills/tldraw/SKILL.md: a copy of .claude/skills/tldraw/SKILL.md.

npm run build regenerates all three. After changing server, web or skill code, rebuild and commit the result. npm run check:plugin fails if the committed plugin is stale.

When you cut a release, bump version in plugins/tldraw/.codex-plugin/plugin.json. Codex caches installs by version.

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)
plugins/tldraw    Codex plugin: manifest, .mcp.json, bundled server, canvas, skill
.agents/plugins/  Codex marketplace entry (what `codex plugin marketplace add` reads)
.claude/skills/   SKILL.md for Claude Code (source of the plugin's copy)
scripts/          Codex plugin build and smoke test
docs/             portable agent guide (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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to read, write, and search local tldraw (.tldr) files, providing a persistent visual scratchpad for diagramming and note organization. It supports full CRUD operations on canvas shapes and metadata management for local canvas files.
      66 npm
      3
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to programmatically control a live Excalidraw canvas through element-level CRUD operations and real-time synchronization. It allows agents to iteratively build, inspect, and refine diagrams while providing visual feedback via screenshots and scene descriptions.
      MIT