tldraw-mcp

Minimal MCP server for editing tldraw .tldr files via JSON manipulation. Headless, no browser needed.

Status

Working skeleton. Schema validation is wired (@tldraw/tlschema validators run before every write), fractional indexing uses @tldraw/utils, file writes are guarded by proper-lockfile. Output verified end-to-end against the real tldraw runtime via Store.loadStoreSnapshot() in the contract test layer.

Tools

File / page lifecycle

Shapes

Discovery & escape hatch (inspired by official tldraw-mcp-app)

Checkpoints (safety)

The token-saving design: tools take primitive args, return ids or ok. The full JSON only enters context when you call get_shape deliberately.

Install

Option 1 · npx (no install, recommended)

npx -y github:m9810223/tldraw-mcp

First run clones, runs npm install, then triggers the prepare script which builds dist/. Subsequent runs are cached.

Pin a branch / tag / commit:

npx -y github:m9810223/tldraw-mcp#main
npx -y github:m9810223/tldraw-mcp#v0.1.0
npx -y github:m9810223/tldraw-mcp#abc1234

Option 2 · Global install

npm install -g github:m9810223/tldraw-mcp
tldraw-mcp   # the bin is on PATH

Option 3 · Private repo over SSH

npx -y git+ssh://git@github.com/m9810223/tldraw-mcp.git

Option 4 · Local clone (for development)

git clone https://github.com/m9810223/tldraw-mcp.git
cd tldraw-mcp
npm install
npm run build
node dist/index.js   # stdio MCP — waits on stdin

Requirements

• Node.js ≥ 20 (enforced by engines.node)

• jq on PATH (only required for the exec_jq tool)

  • macOS: brew install jq

  • Debian/Ubuntu: sudo apt-get install -y jq

Wire up to Claude Code

claude mcp add (recommended). The -- separator is required so -y is passed to npx instead of being parsed as a claude mcp add flag:

claude mcp add tldraw -- npx -y github:m9810223/tldraw-mcp

Add -s user for global (all projects) or -s project for a .mcp.json checked into the repo. Default is -s local (this project, your machine).

…or by editing .mcp.json (project) / ~/.claude.json (user-global):

{
  "mcpServers": {
    "tldraw": {
      "command": "npx",
      "args": ["-y", "github:m9810223/tldraw-mcp"]
    }
  }
}

If you installed globally with Option 2:

{
  "mcpServers": {
    "tldraw": { "command": "tldraw-mcp" }
  }
}

Restart Claude Code, then /mcp should list the tldraw server with 17 tools.

Wire up to other MCP clients

Same JSON shape, different config file location:

Bootstrapping a .tldr file

Use the create_empty_file tool, or save an empty canvas from tldraw.com and point tools at the absolute path.

create_empty_file({ file: "/tmp/demo.tldr" })

Design comparison vs official tldraw-mcp-app

The Cloudflare-hosted official MCP exposes only search + exec (run any JS in a live tldraw Editor). This skeleton goes the opposite way — typed JSON edits over .tldr files — and borrows the discovery pattern (search_api) and escape hatch (exec_jq) so an LLM can fall through when typed tools don't cover an operation.

Known gaps

• index (z-order) only supports appending above the current max — no insert-between

• No alignment / distribution tools (use update_shape to set x/y directly, or exec_jq)

• No image / video / asset support

• Schema version pinning is informational only — opening a file in a newer tldraw may trigger migrations

• search_api curated list is hand-maintained alongside the live @tldraw/tlschema reflection

Architecture

src/
  index.ts       MCP server entry, tool registration (stdio transport)
  tools.ts       Tool handlers + zod input schemas
  shapes.ts      tldraw record factories (geo/text/arrow/group/binding)
  store.ts       Load/save .tldr + withFileLock; helpers (id gen, indexing, find, page-of-shape, bindings-for-shape)
  template.ts    Empty .tldr generator using @tldraw/tlschema serialize()
  validate.ts    validateShape / validateBinding using createShapeValidator + createBindingValidator
  checkpoint.ts  Timestamped backups under .tldraw-mcp-checkpoints/
  jq.ts          Shell-out to jq for the exec_jq escape hatch

test/
  unit/          store + validate (13 tests)
  integration/   tools end-to-end on tmp .tldr (18 tests)
  contract/      loadStoreSnapshot against real @tldraw/store (4 tests)

Pure JSON manipulation — no @tldraw/store, no DOM, no React.