Tldraw Offline

A Bun + Hono MCP server that gives a remote agent complete control of tldraw Desktop's local Canvas API, durable document-script workspaces, assets, and screenshots.

The server runs on the Mac beside tldraw. Remote clients receive virtual workspace paths and inline MCP images—never unusable Mac paths or the app's bearer token.

TODO

• should be managed by neo
• efficiency around mcp docs reading requests

Requirements

• macOS with tldraw Desktop and its Canvas API
• Bun
• an MCP client supporting Streamable HTTP
• Tailscale for the recommended remote transport

Install

`git clone https://github.com/er1chi/tldraw-mcp.git`
bun install
bun run check

Start

Export a stable bearer token, then run the start script:

export TLDRAW_MCP_TOKEN="$(bun run --silent token)"
bun run start

The script starts the MCP server on 127.0.0.1:7237 and runs Tailscale Serve in HTTP-only mode on port 80. It prints the remote MCP URL and keeps both processes in the foreground until you press Ctrl-C.

Local endpoints:

• http://127.0.0.1:7237/mcp
• http://127.0.0.1:7237/healthz
• authenticated http://127.0.0.1:7237/readyz

Test the local endpoint with the official MCP client:

TLDRAW_MCP_URL=http://127.0.0.1:7237/mcp \
TLDRAW_MCP_TOKEN="$TLDRAW_MCP_TOKEN" \
  bun scripts/smoke.ts

Configure a remote MCP client

Copy the printed HTTP endpoint and bearer token to the trusted Linux host. A generic Streamable HTTP configuration looks like:

{
  "mcpServers": {
    "tldraw-offline": {
      "url": "http://DEVICE.TAILNET.ts.net/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_TOKEN"
      }
    }
  }
}

The exact configuration location depends on the MCP host. Keep the endpoint restricted with Tailscale ACLs as well as the bearer token.

Install skill/tldraw-offline/SKILL.md on the Linux agent host. If this repository is present there:

./scripts/install-skill.sh

Tool surface

Discovery and reference

• tldraw_health
• tldraw_docs_list
• tldraw_doc_inspect — uses the focused document when documentId is omitted; optionally includes bindings
• tldraw_reference_search
• tldraw_imports_search
• tldraw_helpers_list
• tldraw_recipes_list
• tldraw_recipe_get
• tldraw_readme

Canvas control

• tldraw_search — complete Canvas API escape hatch
• tldraw_exec — complete live Editor escape hatch
• tldraw_lint
• tldraw_screenshot — inline JPEG MCP content

Durable scripts and assets

• tldraw_workspace_open
• tldraw_workspace_list
• tldraw_workspace_read
• tldraw_workspace_apply
• tldraw_script_status
• tldraw_script_error_log

The workspace API exposes only virtual script/** and assets/** paths for writes. Existing files use SHA-256 preconditions, exact edits require one unique match, complete buffers are written in watcher-compatible order, and entrypoints are committed last.

Configuration

Copy .env.example to .env, set TLDRAW_MCP_TOKEN, and update any values you want to override.

Development

bun run dev
bun run typecheck
bun test
bun run check

operator-guide/guide.md is served as tldraw://guide. The MCP-native agent skill is under skill/tldraw-offline/.

Cool Examples

• https://x.com/max__drake/status/2078151243650810198?s=20
• https://x.com/tldraw/status/2078164903911719305?s=20
• https://x.com/shubgaur/status/2078309824199074020?s=20