Codex Tldraw

npm version CI License: MIT

A Codex stdio MCP server that turns local repository context or a prompt-provided plan into a tldraw diagram saved as a .tldr snapshot.

Quick Start

Add the server to Codex:

codex mcp add codex-tldraw -- npx -y codex-tldraw-mcp

Then ask Codex to diagram the current repo:

Use codex-tldraw to diagram this repo.

Or ask for a diagram directly:

Use codex-tldraw to draw a password reset state machine.

The default output is:

<repo>/boards/main.tldr

Open the generated board in a tldraw-compatible viewer.

What You Get

• A repo-local .tldr board that stays with the project it explains.
• A user-facing product workflow inferred from package metadata and source text.
• A prompt-driven offline canvas API for drawing workflows, state machines, plans, and architecture sketches that are not tied to repo scanning.
• tldraw steps and arrows laid out left to right.
• Non-destructive updates: existing boards get the next diagram appended to the right.
• MCP resources for listing boards and reading board summaries.

For a handwriting font app, the workflow may be inferred as:

User writes alphabet on paper -> User takes a photo of the paper -> User uploads the image -> AI generates a font -> User downloads a .ttf file

Manual Configuration

If you prefer editing Codex MCP config directly:

[mcp_servers.codex-tldraw]
command = "npx"
args = ["-y", "codex-tldraw-mcp"]

Tools

• diagram_repo: scans a repo and appends a product workflow diagram to <repo>/boards/<boardName>.tldr.
• draw_canvas: appends a prompt-provided workflow, state machine, architecture sketch, or plan to <repo>/boards/<boardName>.tldr.
• list_boards: lists boards under a repo's boards/ directory.
• read_board_summary: summarizes generated diagrams and shape counts.

Each tool accepts an optional repoPath. Relative paths are resolved from the MCP server working directory.

Board resources list and read boards from the most recent repoPath used by a tool call. Before any tool call, resources default to the MCP server working directory.

Prompt-Driven Diagrams

draw_canvas does not scan source files. The current repository is only the storage location for the generated board.

Example prompts:

Use codex-tldraw to draw the auth flow:
Visitor opens login -> chooses email or SSO -> completes MFA -> lands in dashboard.

Use codex-tldraw to make a state machine for password reset:
Idle -> Reset requested -> Email sent -> Token verified -> Password updated.

Use codex-tldraw to append an architecture diagram for this plan:
Web app calls API gateway, API gateway calls worker queue, worker writes generated files to object storage.

Feedback

This project is early and feedback is useful. Please open an issue if:

• The generated workflow misses the real product flow.
• A board does not open in your tldraw-compatible viewer.
• You have a messy repo where a PM and engineer need a clearer shared map.

Use the GitHub issue templates for bugs, feature requests, and real-world examples.

Why This Exists

This project is snapshot-only. It does not control a live browser canvas or provide live collaboration. It writes board files to the repository being diagrammed so a tldraw-compatible viewer can open them later.

The official tldraw MCP App is designed for hosts that can render an interactive tldraw canvas inside the chat context. In Codex Desktop, tool discovery worked in testing, and the tldraw search tool returned Editor API details, shape types, and helpers. The live exec path did not work: every call timed out after 30 seconds, including a read-only call to count the current page shapes.

That failure mode suggested a host compatibility gap, not a tldraw file format problem. Codex can reliably call local stdio MCP tools and inspect generated files, but it does not currently provide the same embedded interactive MCP App canvas path used by hosts such as Cursor.

This server is the Codex-first fallback. Instead of trying to drive a live canvas, it generates .tldr snapshots on disk through a normal stdio MCP tool call. The result is less interactive, but it works reliably in Codex and keeps the generated board with the repository it explains.

Security

This is a local filesystem tool. It reads source files from repoPath and writes .tldr files under repoPath/boards.

To restrict access to specific directories, set TLDRAW_MCP_ALLOWED_ROOTS to a path-delimited allowlist:

[mcp_servers.codex-tldraw]
command = "npx"
args = ["-y", "codex-tldraw-mcp"]
env = { TLDRAW_MCP_ALLOWED_ROOTS = "/Users/me/dev:/Users/me/work" }

When the allowlist is set, repoPath must resolve inside one of those roots.

Generated .tldr files do not store absolute local repository paths in shape metadata.

Local Development

This repo uses Bun for development:

bun install
bun run build
bun run smoke

Run the server from source:

bun run dev

Use a local build in Codex:

[mcp_servers.codex-tldraw]
command = "node"
args = ["/absolute/path/to/codex-tldraw-mcp/dist/index.js"]

Publish

Build, test, and inspect the package contents:

bun install --frozen-lockfile
bun run build
bun run smoke
bun run check:package

Publishing is handled by .github/workflows/publish-npm.yml when a GitHub Release is published. The npm trusted publisher must allow jananadiw/codex-tldraw-mcp, workflow publish-npm.yml, with no GitHub environment and the publish action enabled. The workflow uses GitHub OIDC and does not require an npm token.

Use the workflow's dry_run dispatch option to validate a release without publishing it.

The package includes MCP Registry metadata:

• package.json declares mcpName.
• server.json describes the npm stdio package.

After the workflow publishes and the npm package version is available, authenticate and publish the registry metadata:

mcp-publisher login github
mcp-publisher publish

Verify the registry entry:

curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.jananadiw/codex-tldraw-mcp"