tldraw-mcp
The tldraw-mcp server lets you programmatically create, edit, and manage tldraw .tldr diagram files through a 26-tool MCP interface — no browser or UI required.
File & Page Management
Create new empty
.tldrfiles (create_empty_file), add pages (create_page), list pages with id/name/index (list_pages), and move shapes between pages (move_to_page)
Shape Operations
Create rectangles (
create_rect), text shapes (create_text), and arrow connections (connect)Group shapes (
create_group) or dissolve groups (ungroup)List shapes with lightweight output (
list_shapes), get a full shape record (get_shape), patch any shape (update_shape), or delete shapes with optional cascade removal of arrows/bindings (delete_shape)
Layout & Formatting
Fit shapes to text content (
fit_to_text), align on an axis (align), distribute evenly (distribute), chain in horizontal/vertical layout (auto_layout), apply Dagre graph layout (graph_layout), measure arrow labels (measure_arrow_labels), bend overlapping arrows symmetrically (bend_overlapping_arrows), or do it all in one shot (polish_layout)
Discovery & Escape Hatch
Introspect supported shape types and props (
search_api), or run arbitraryjqfilters against the raw file JSON with optional write-back (exec_jq)
Checkpoints & Safety
Save timestamped backups (
save_checkpoint), list available backups (list_checkpoints), and restore from a checkpoint (restore_checkpoint)
Underpinned by pure Node.js JSON manipulation with schema validation, fractional indexing, and file locking.
Provides tools for creating and editing tldraw files (.tldr) via JSON manipulation, including shape creation (rectangles, text, groups, arrows), page management, and file checkpoints.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@tldraw-mcp Add a new page named 'Design Notes'"
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-m9810223
A Claude Code plugin: 26-tool MCP server for editing tldraw .tldr files via JSON manipulation (headless, no browser needed), plus a tldraw-screenshot skill that renders a .tldr to PNG via tldraw.com so Claude can SEE the diagram.
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.
Related MCP server: obsidian-codex-mcp
Quick Start
Requires Node ≥ 20.
1. Install as a Claude Code plugin (one command registers the marketplace, the second installs the bundled MCP server + skill):
claude plugin marketplace add m9810223/tldraw-m9810223
claude plugin install tldraw-m9810223@tldraw-m9810223Restart Claude Code. /mcp lists tldraw-m9810223 (26 tools); /plugin lists tldraw-m9810223; the tldraw-screenshot skill is available too.
If you'd rather wire just the MCP server (no skill), see Install / Update / Remove below.
2. Try the demo prompt in Claude Code:
Draw the Shai-Hulud supply-chain attack flow described in this article with MCP `tldraw-m9810223`, save to `./demo.tldr`:
https://semgrep.dev/blog/2026/malicious-dependency-in-pytorch-lightning-used-for-ai-training/
- Match the actors and how data/control flows between them
- Polish the result at the end3. View the result — drop ./demo.tldr onto tldraw.com, or use the tldraw VS Code extension for live preview.

Source file: docs/demo.tldr
Tools
File / page lifecycle
Tool | What it does |
| Create a fresh |
| Add a new page |
| List pages with id, name, ordering index |
| Move shapes; |
Shapes
Tool | What it does |
| Create a rectangle (geo shape) |
| Create a text shape |
| Group shapes by reparenting them |
| Dissolve a group, reparenting its children to the group's parent |
| Arrow + bindings between two same-page shapes |
| List shapes — id, type, x, y, label only |
| Full record of one shape by id |
| Shallow-merge patch (use nested |
| Delete by id; |
Layout / text fitting
Tool | What it does |
| Resize a geo/text shape to fit its current text content |
| Align shapes on an axis (left/right/top/bottom/center-x/center-y) |
| Even-space shapes between the outermost two |
| Lay shapes out in a horizontal/vertical chain |
| Dagre layout for arrow-connected shapes (best for non-chain topologies) |
| Report label sizes + endpoint distances for labeled arrows |
| Bend parallel arrows (same shape pair) symmetrically; |
| One-shot finisher: |
Discovery & escape hatch
Tool | What it does | Token cost |
| List supported shape types + curated required props. Pass | low / medium |
| Run a | varies |
Checkpoints (safety)
Tool | What it does | Token cost |
| Copy | low |
| List backups, newest first | low |
| Restore a backup (most recent if | low |
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 / Update / Remove
jq only needed for exec_jq (brew install jq / apt-get install jq).
As a plugin (recommended — bundles MCP server + skill)
# Install (user scope by default)
claude plugin marketplace add m9810223/tldraw-m9810223
claude plugin install tldraw-m9810223@tldraw-m9810223
# Update
claude plugin update tldraw-m9810223
# Remove
claude plugin uninstall tldraw-m9810223
claude plugin marketplace remove tldraw-m9810223
rm -rf ~/.claude/plugins/cache/tldraw-m9810223 # optional — also drop the cached clone
# Verify clean (both should print nothing)
claude plugin list | grep tldraw
claude mcp list | grep -i tldrawMCP server only (no skill)
Use this if you want the editing tools but not the screenshot skill, or you're on a Claude client that doesn't speak Code's plugin system.
# Install — user scope: every project on this machine
claude mcp remove tldraw-m9810223 -s user 2>/dev/null; rm -rf ~/.npm/_npx
claude mcp add -s user tldraw-m9810223 -- npx -y github:m9810223/tldraw-m9810223
# Install — local scope (default): only the current project directory
claude mcp remove tldraw-m9810223 2>/dev/null; rm -rf ~/.npm/_npx
claude mcp add tldraw-m9810223 -- npx -y github:m9810223/tldraw-m9810223The first arg (tldraw-m9810223) is the local server name — pick whatever you like, then refer to it the same way in subsequent commands. Restart Claude Code, then /mcp lists it with 26 tools.
Wire up to other MCP clients
Same JSON shape, different config file location:
Client | Config path |
Claude Desktop |
|
Cursor |
|
VS Code |
|
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" })Viewing / editing the output
Tool | Notes |
| Programmatic render to PNG via |
Drag the | |
Native | |
Tldraw Desktop / official editor | Drop the file in |
The VS Code extension is the smoothest dev loop — keep code path/to/file.tldr open in a tab while the MCP edits it; the editor refreshes on disk change.
The tldraw-screenshot skill is the smoothest agent loop — Claude edits via the MCP, renders via the skill, looks at the PNG, edits again. See skills/tldraw-screenshot/SKILL.md for the workflow and gotchas. Requires playwright-cli on PATH.
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.
Official | This skeleton | |
Transport | streamable-http + sse (Cloudflare) | stdio (works in Claude Code directly) |
Runtime | Real tldraw Editor in widget iframe | Pure Node, edits raw JSON |
Tools | 2 ( | 26: file/page (4) + shape (9) + layout (8) + discovery (2) + ckpt (3) |
Live preview | Yes (widget iframe) | No (open the file in tldraw to view) |
Coverage | Whole Editor API | Geo / text / arrow + jq escape hatch |
Known gaps
index(z-order) only supports appending above the current max — no insert-betweenNo image / video / asset support
Schema version pinning is informational only — opening a file in a newer tldraw may trigger migrations
search_apicurated list is hand-maintained alongside the live@tldraw/tlschemareflection
Architecture
.claude-plugin/
plugin.json Plugin metadata + pointers to mcpServers + skills
marketplace.json Marketplace manifest so `claude plugin install` can find this
.mcp.json Plugin-scoped MCP server declaration (npx-from-github)
skills/
tldraw-screenshot/
SKILL.md Workflow for rendering .tldr → PNG via playwright-cli + tldraw.com
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
text-metrics.ts Text size heuristics for autoFit + label measurement
graph-layout.ts Dagre wrapper for graph_layout
arrow-bending.ts Detect parallel-edge overlap + assign symmetric bend values
test/
unit/ store + validate + text-metrics + arrow-bending (34 tests)
integration/ tools end-to-end on tmp .tldr (39 tests)
contract/ loadStoreSnapshot against real @tldraw/store (4 tests)
boundary/ N-1 / N / N+1 limits + concurrent writes (89 tests)Pure JSON manipulation — no @tldraw/store, no DOM, no React.
Available Tools
18 toolsconnectA
Connect two shapes with an arrow. Arrow position is binding-driven (start/end stored as 0,0 fallback). Returns arrow id + binding ids.
Inputs: file (required), fromId (required), toId (required), text.
create_empty_fileA
Create a new empty .tldr file with one default page. Errors if file exists unless overwrite=true.
Inputs: file (required), overwrite.
create_groupA
Group existing shapes into a new group. Reparents the given shape ids under a new group shape.
Inputs: file (required), childIds (required).
create_pageB
Create a new page in the document. Returns the new page id.
Inputs: file (required), name (required).
create_rectC
Create a rectangle shape on the main page. Returns its id.
Inputs: file (required), x (required), y (required), w (required), +3 more.
create_textC
Create a text shape on the main page. Returns its id.
Inputs: file (required), x (required), y (required), text (required), +2 more.
delete_shapeC
Delete a shape by id.
Inputs: file (required), id (required), cascade.
exec_jqA
Escape hatch: run a jq filter against the .tldr JSON. Set write=true to persist (auto-checkpoints first).
Inputs: file (required), filter (required), write.
get_shapeB
Get the full record of a single shape by id.
Inputs: file (required), id (required).
list_checkpointsA
List checkpoint backups for a .tldr file, newest first.
Inputs: file (required).
list_pagesB
List all pages with id, name, and ordering index.
Inputs: file (required).
list_shapesA
List shapes (id, type, x, y, label only - props omitted to save tokens).
Inputs: file (required), type.
move_to_pageB
Move shapes to a different page by reparenting them. Note: arrows and bindings should move together for correctness.
Inputs: file (required), shapeIds (required), pageId (required), bindings.
restore_checkpointA
Restore a checkpoint over the .tldr file. Omits checkpoint to restore the most recent.
Inputs: file (required), checkpoint.
save_checkpointA
Copy the .tldr file to a timestamped backup. Returns the backup path.
Inputs: file (required), label.
search_apiA
List supported tldraw shape types and their required props. Use this to discover what can be created before falling back to exec_jq.
Inputs: query, type, verbose.
ungroupA
Dissolve a group: reparent its children to the group's parent and delete the group shape.
Inputs: file (required), groupId (required).
update_shapeA
Update a shape via shallow merge. Pass nested {"props": {...}} to update props.
Inputs: file (required), id (required), patch (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 18 tools
Each tool has a clearly distinct purpose, from creating shapes and pages to managing checkpoints and connecting shapes. The exec_jq escape hatch is intentionally broad but its role as a fallback is well-documented, avoiding confusion.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., create_rect, list_pages, update_shape). No mixed conventions or ambiguous verbs.
With 18 tools, the set is well-scoped for a drawing application: it covers shape CRUD, grouping, pages, checkpoints, and an escape hatch. The count feels complete without being overwhelming.
The toolset covers core operations but misses explicit tools for creating non-rectangle shapes (e.g., ellipses, lines). However, search_api and exec_jq fill these gaps, so agents can still achieve full functionality.
Maintenance
Related MCP Connectors
Collaborative whiteboard MCP server — create objects, connectors, C4 diagrams, and manage boards
Hosted MCP server for Obsidian Sync vaults: read, search, edit notes. Not affiliated with Obsidian.
Related MCP Servers
- AlicenseAqualityDmaintenanceA 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.92MIT
- AlicenseAqualityCmaintenanceLocal-first MCP server for working with an Obsidian vault. No API key required1719MIT
- AlicenseNot gradedqualityBmaintenanceA Codex stdio MCP server that generates simple tldraw product workflow diagrams as .tldr files.125 npm25MIT
- FlicenseNot gradedqualityDmaintenanceMCP server that exposes an Obsidian vault (search, read, create, and update notes) via Streamable HTTP.-