tldraw

You run a local MCP server that directly reads, writes, and searches persistent tldraw canvas files (.tldr) on disk. This enables AI agents to programmatically update and query real canvases stored on your machine, making tldraw a persistent visual scratchpad you can automate.

How to use

To use this MCP server, run it from your environment and connect your MCP client or automation tool to the provided command. The server exposes endpoints for reading, writing, listing, and searching local tldraw canvases, as well as performing shape CRUD operations to manage the contents of those canvases.

How to install

Prerequisites you need before installing: a modern runtime environment for JavaScript/TypeScript, such as Node.js, and the Bun toolkit for development flows mentioned here.

Quick start (no build required): you can run the MCP server directly with a one-liner.

npx @talhaorak/tldraw-mcp

If you prefer building from source, follow these steps to clone and run locally.

git clone https://github.com/talhaorak/tldraw-mcp.git
cd tldraw-mcp
bun install
bun run start

Configuration and runtime details

Environment variables you may configure for the MCP server include the base directory that stores your .tldr files.

TLDRAW_DIR=/path/to/your/tldraw/files

How to configure clients to connect

Use the standard MCP client configuration to point at the local server. The server is intended for local file operations, so you configure the client to call the server through the designated command and environment setup shown in your environment integrations.

Security and safety notes

All operations are designed to stay within the specified base directory and validate writes against the tldraw schema. There is no network access beyond local IPC or process boundaries when used as a local server.

Troubleshooting and tips

If you encounter issues with path resolution or file validation, verify that TLDRAW_DIR points to the correct folder containing your .tldr files and that the server has permission to read and write within that directory.

Notes on capabilities and file format

This server operates on the tldraw v2 file format, enabling comprehensive read, write, list, and search capabilities, as well as programmatic shape CRUD operations.

Development and publishing workflow

Developers can install dependencies, run type checks, build, and run tests as part of their workflow. Use the provided scripts to publish new versions with automated version bumps and Git metadata updates when applicable.

Available tools

tldraw_read

Read a .tldr file and return its parsed content.

tldraw_write

Write or update a .tldr file with validation against the tldraw schema.

tldraw_create

Create a new empty tldraw canvas file.

tldraw_list

List all .tldr files with metadata such as page and shape counts.

tldraw_search

Search text content across all canvases.

tldraw_get_shapes

Retrieve all shapes from a file, optionally filtered by page.

tldraw_add_shape

Add a new shape to a canvas.

tldraw_update_shape

Update properties of an existing shape.

tldraw_delete_shape

Delete a shape from a canvas.