tl-draw-mcp
Provides tools for creating, updating, deleting shapes and retrieving canvas state on a live tldraw canvas, enabling AI agents to draw diagrams and flowcharts in real time.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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 serverIf 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.jsOn 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\tldrawCodex
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-mcpThen restart Codex. The CLI and the desktop app share the same install.
Update |
|
Uninstall |
|
Port or timeout | Export |
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.mjsOr 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
Start your agent in any project.
The first tool call spins up the server — open
http://localhost:3030.The badge at the bottom-right reads
tldraw MCP · connected.Prompt: "Draw a flowchart of the login flow."
Tools
Tool | What it does |
| Node-and-edge diagram with automatic layout. Use this for any graph. |
| Shapes at explicit positions — free-form drawing, wireframes, annotation. |
| Bound connectors between shapes that already exist. |
| Change position, size, colour or text by id. |
| Remove shapes by id, or |
| 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 :5173The 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 CodexConfiguration
Variable | Default | Meaning |
|
| Preferred port; falls back to 3031, 3032, … if taken. |
|
| 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 |
Badge says | Protocol mismatch after an upgrade — rebuild ( |
Port :3030 busy | Automatic fallback to :3031 etc. The real URL is in the MCP logs ( |
| Retry with |
MIT — see LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Whiteboard where any shape opens into another canvas. Claude Code and Codex plugins render plans on it.
Give Claude a whiteboard: notes, links, images and diagrams on a board you both see and edit.
Online whiteboard your AI agent draws on: live shared canvases, solo or with your team.
Create and edit architecture diagrams from your AI agent; get an SVG and a live editable canvas.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables 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 npm3MIT
- AlicenseAqualityDmaintenanceEnables AI agents to programmatically generate, edit, and view Excalidraw diagrams with real-time browser synchronization. It provides a suite of tools for adding shapes, text, and arrows to diagrams through natural language interactions.11101MIT
- AlicenseNot gradedqualityDmaintenanceEnables 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
- FlicenseNot gradedqualityDmaintenanceEnables Claude to create, open, and edit persistent tldraw whiteboards in real-time, with live collaboration between human and AI.1-