tldraw

tldraw MCP 应用

这是 tldraw MCP 应用。它通过 Model Context Protocol app specification 向 AI Agent 提供可交互的 tldraw 画布，因此你可以在任何支持 MCP app 规范的 MCP 客户端中与 Agent 一起使用 tldraw。

架构

该应用由两部分组成：服务端和小组件。

服务端

服务端通过 src/worker.ts 在 Cloudflare Workers 上运行，使用由 SQLite 支持的 Durable Object（TldrawMCP）持久化存储检查点。

它提供以下工具：

• search — 在沙盒化的动态 Worker 中查询提取出的 Editor API 规范
• exec — 通过待处理请求回调桥接，在小组件中的实时编辑器上执行 JavaScript
• _exec_callback — 仅供应用使用的工具，由小组件调用以完成待处理的 exec 请求
• save_checkpoint / read_checkpoint — 仅供应用使用的工具，由小组件用于持久化检查点

小组件

小组件是一个 React 应用（src/widget/mcp-app.tsx），在 MCP 宿主的 iframe 中渲染完整的 tldraw 画布。

AI 调用 exec 时，服务端会创建一个待处理请求，小组件会获取该请求，并通过一个聚焦的编辑器代理（src/widget/focused/）运行代码。该代理会在便于 AI 使用的形状格式（简单字符串 ID、扁平的 _type 形状）和 tldraw 的内部 TLShape/TLShapeId 类型之间进行转换，然后调用 _exec_callback，以结果完成待处理请求。画布状态会保存到 Durable Object 的 SQLite 数据库和浏览器本地存储中。

开发

前置条件

小组件构建依赖生成的文件（editor-api.json、method-map.json），这些文件是从编辑器的 TypeScript 声明中提取的。开发或构建 mcp-app 之前，需要先构建核心软件包：

# from the repo root
pnpm build

这会生成 .tsbuild/ 输出，供 pnpm extract-api 读取。build 和 dev 脚本会自动运行 extract-api，因此无需单独调用。

软件包脚本

在 apps/mcp-app 目录中运行所有命令。

命令	作用
pnpm build	构建小组件 HTML
pnpm dev	构建小组件 + 启动本地 Cloudflare Worker（在 localhost:8787 上运行 HTTP MCP）
pnpm dev:tunnel	构建小组件 + 启动稳定的命名 Cloudflare 隧道 + 本地 Worker，并将 WORKER_ORIGIN 设置为隧道 URL
pnpm run deploy	构建小组件 + 将 Cloudflare Worker 部署到生产环境

pnpm dev:tunnel 要求在你的机器上安装 cloudflared CLI，并且需要一次性运行 cloudflared tunnel login。它通过命名隧道提供稳定的每用户主机名（<user>-mcp-app-dev.tldraw.xyz），因此你在托管 MCP 客户端中注册的 URL 在多次运行期间保持不变，而不会每次都变化。用户标识默认值为 whoami；可使用 MCP_TUNNEL_USER、MCP_TUNNEL_ZONE 和 PORT 覆盖它（或区域/端口）。该区域必须托管在 Cloudflare 上（tldraw.xyz 符合要求；tldraw.dev/tldraw.com 托管在 Vercel 上，无法使用）。

在 wrangler.toml 中，Worker 默认采用适用于生产环境的安全行为，包括将 MCP_IS_DEV="false" 设为环境变量。本地 HTTP 开发脚本会将其覆盖为 MCP_IS_DEV=true，以便本地 Claude/ChatGPT 连接器禁用 ui.domain，而生产部署会继续启用该设置。

Cursor 配置

在 ~/.cursor/mcp.json 中添加以下两个服务：

{
	"mcpServers": {
		"tldraw": {
			"transport": "http",
			"url": "https://tldraw-mcp-app.tldraw.workers.dev/mcp"
		},
		"tldraw-local": {
			"command": "npx",
			"args": ["-y", "mcp-remote", "http://127.0.0.1:8787/mcp"]
		}
	}
}

Claude Desktop 本地配置

进行 Claude Desktop 本地开发时，使用 claude_desktop_config.json 和本地 HTTP 服务端：

{
	"mcpServers": {
		"tldraw-local": {
			"command": "npx",
			"args": ["-y", "mcp-remote", "http://127.0.0.1:8787/mcp"]
		}
	}
}

Claude Desktop 远程设置

如果你想在 Claude Desktop 中试用远程 MCP 服务，请使用应用内连接器流程，而不要将生产环境 URL 添加到 claude_desktop_config.json。

1. 打开 Claude Desktop
2. 在侧边栏中，前往 自定义
3. 打开 连接器
4. 点击添加连接器的按钮，然后选择 添加自定义连接器
5. 为其命名，例如 tldraw
6. 将 https://tldraw-mcp-app.tldraw.workers.dev/mcp 粘贴为服务 URL

免费方案不提供 添加自定义连接器 选项，因此你可能需要 Max 或其他付费方案。

如果你需要在 Claude Desktop 中访问 Notion，请另外使用 Notion MCP 连接器。

ChatGPT 本地开发

ChatGPT 需要 HTTPS 源站，因此你需要 Cloudflare 隧道。你必须是 OpenAI 组织／工作区的管理员才能进行本地开发。

首次设置（每台机器只需一次）：

1. 运行 cloudflared tunnel login 并选择 tldraw.xyz 区域

之后每次会话：

1. 在 apps/mcp-app 中运行 pnpm dev:tunnel
2. 它会提供你的固定主机名，例如 https://<user>-mcp-app-dev.tldraw.xyz（首次运行还会创建具名隧道及其 DNS 路由）
3. 在 ChatGPT 网页版（而非桌面应用）中，前往 应用，并使用该 URL 添加你的应用
4. 然后，你可以在 ChatGPT 网页版以及桌面或移动应用中进行测试

由于每位用户的主机名都是固定的，你只需在 ChatGPT 中添加一次应用——之后运行 pnpm dev:tunnel 都会重复使用同一个 URL。

dev:tunnel 会自动将 WORKER_ORIGIN 连接到固定隧道 URL，并为本地 worker 设置 MCP_IS_DEV=true。

迭代流程

1. 在 apps/mcp-app 中修改代码
2. 运行相关脚本（dev 或 dev:tunnel）
3. 在客户端中断开并重新连接 MCP 服务（或重新加载页面／应用）
4. 修改 widget 时，确保重新构建，可以运行 pnpm build，也可以重新运行任一开发脚本。

修改后重新连接服务是获取新代码最可靠的方式，尤其是在 widget HTML 发生变化时。

会话存储生命周期

每个 MCP 会话都是一个 TldrawMCP Durable Object。它最多保留 MAX_CHECKPOINTS（50）个画布快照，并会在未保存检查点达 IDLE_TTL_MS（7 天）后销毁自身——该计划在 init() 中启动，并在每次检查时重新启动。

联系我们

欢迎在 Twitter/X 上关注我们：@tldraw。

社区

有问题、意见或反馈？加入我们的 Discord。如需了解最新消息和发行说明，请访问 tldraw.dev。