tldraw

tldraw MCP アプリ

これは tldraw MCP アプリです。Model Context Protocol アプリ仕様を通じて、インタラクティブな tldraw キャンバスを AI エージェントに公開します。これにより、MCP アプリ仕様をサポートする任意の MCP クライアントで、エージェントと一緒に tldraw 内で作業できます。

アーキテクチャ

このアプリは 2 つの部分で構成されています: サーバーとウィジェットです。

サーバー

サーバーは、src/worker.ts を介して Cloudflare Workers 上で動作し、SQLite に支えられた Durable Object（TldrawMCP）を使用してチェックポイントを永続的に保存します。

公開しているもの:

• search — サンドボックス化された動的ワーカー内で、抽出された Editor API 仕様をクエリします
• exec — 保留中リクエストのコールバックブリッジを介して、ウィジェット内のライブエディターに対して JavaScript を実行します
• _exec_callback — ウィジェットが保留中の exec リクエストを解決するために呼び出す、アプリ専用ツール
• save_checkpoint / read_checkpoint — ウィジェットがチェックポイントの永続化に使用する、アプリ専用ツール

ウィジェット

ウィジェットは React アプリ（src/widget/mcp-app.tsx）で、MCP ホストの iframe 内に完全な tldraw キャンバスをレンダリングします。

AI が exec を呼び出すと、サーバーが保留中リクエストを作成し、ウィジェットがそれを受け取ります。ウィジェットは、AI に扱いやすいシェイプ形式（シンプルな文字列 ID、フラットな _type シェイプ）と tldraw 内部の TLShape/TLShapeId 型との間を変換する専用エディタープロキシ（src/widget/focused/）を通じてコードを実行し、その後 _exec_callback を呼び出して保留中リクエストを結果で解決します。キャンバスの状態は、Durable Object の SQLite データベースとブラウザーのローカルストレージにチェックポイントされます。

開発

前提条件

ウィジェットのビルドは、エディターの TypeScript 宣言から抽出される生成ファイル（editor-api.json、method-map.json）に依存しています。mcp-app を開発またはビルドする前に、まずコアパッケージをビルドする必要があります:

# from the repo root
pnpm build

これにより、pnpm extract-api が読み取る .tsbuild/ 出力が生成されます。build および dev スクリプトは extract-api を自動的に実行するため、別途呼び出す必要はありません。

パッケージスクリプト

すべてのコマンドは apps/mcp-app から実行してください。

コマンド	実行内容
pnpm build	ウィジェットの HTML をビルド
pnpm dev	ウィジェットをビルド + ローカル Cloudflare ワーカーを起動（localhost:8787 で HTTP MCP）
pnpm dev:tunnel	ウィジェットをビルド + 安定した名前付き Cloudflare トンネル + ローカルワーカーを起動（WORKER_ORIGIN をトンネル URL に設定）
pnpm run deploy	ウィジェットをビルド + Cloudflare ワーカーを本番環境にデプロイ

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 でデフォルトで本番環境に安全な動作をするよう設定されており、MCP_IS_DEV="false" の設定も含まれます。ローカル HTTP 開発スクリプトはこれを MCP_IS_DEV=true で上書きするため、ローカルの Claude/ChatGPT コネクターは ui.domain を抑制しますが、本番環境のデプロイでは有効のままになります。

Cursor のセットアップ

~/.cursor/mcp.json に次の 2 つのサーバーを追加します:

{
	"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 開発では、ローカル HTTP サーバーを使用して claude_desktop_config.json を設定します:

{
	"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. サイドバーで Customize に移動します
3. Connectors を開きます
4. コネクターを追加するボタンをクリックし、Add custom connector を選択します
5. tldraw などの名前を付けます
6. サーバー URL として https://tldraw-mcp-app.tldraw.workers.dev/mcp を貼り付けます

Add custom connector オプションは無料プランでは利用できないため、Max などの有料プランが必要になる場合があります。

Claude Desktop で Notion へのアクセスが必要な場合は、別途 Notion MCP コネクターを使用してください。

ChatGPT でのローカル開発

ChatGPT は HTTPS オリジンを必要とするため、Cloudflare トンネルが必要です。ローカル開発を行うには、OpenAI 組織/ワークスペースの管理者である必要があります。

初回セットアップ (マシンごとに 1 回):

1. cloudflared tunnel login を実行し、tldraw.xyz ゾーンを選択します

その後、毎回のセッションで:

1. apps/mcp-app で pnpm dev:tunnel を実行します
2. 安定したホスト名 (例: https://<user>-mcp-app-dev.tldraw.xyz) で提供されます (初回実行時には名前付きトンネルとその DNS ルートも作成されます)
3. ChatGPT のウェブ版 (デスクトップアプリではありません) で Apps に移動し、その URL を使ってアプリを追加します
4. その後、ChatGPT のウェブ版とデスクトップまたはモバイルアプリの両方でテストできます

ホスト名はユーザーごとに安定しているため、ChatGPT でアプリを追加するのは 1 回だけで済みます。以降の pnpm dev:tunnel の実行では同じ URL が再利用されます。

dev:tunnel は WORKER_ORIGIN を安定したトンネル URL に自動的に接続し、ローカルワーカーに対して MCP_IS_DEV=true を設定します。

イテレーションループ

1. apps/mcp-app でコードを変更します
2. 該当するスクリプト (dev または dev:tunnel) を実行します
3. クライアントで MCP サーバーを切断して再接続します (またはページ/アプリを再読み込みします)
4. ウィジェットを変更する場合は、pnpm build を実行するか、いずれかの開発スクリプトを再実行して、必ず再ビルドしてください。

変更後にサーバーを再接続することが、新しいコード (特にウィジェットの HTML が変更された場合) を取り込む最も確実な方法です。

セッションストレージのライフサイクル

各 MCP セッションは TldrawMCP Durable Object です。最大 MAX_CHECKPOINTS (50) 個のキャンバススナップショットを保持し、チェックポイントの保存なしで IDLE_TTL_MS (7 日間) が経過すると自身を破棄します。このスケジュールは init() で設定され、チェックごとに再設定されます。

お問い合わせ

Twitter/X で @tldraw を見つけてください。

コミュニティ

質問、コメント、フィードバックがありますか? Discord に参加してください。最新ニュースとリリースノートについては、tldraw.dev をご覧ください。