Codex Tldraw MCP server

codex-tldraw-mcp

A stdio MCP server that generates editable repo-local tldraw diagrams, portable SVG previews, and trackable code graphs with drift detection.

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.

Reverse-engineer its runtime architecture:

Use codex-tldraw to show how this repo works across its main components.
Show the main flow first, keep short errors inside components, and label each interaction once.

Or ask for a diagram directly:

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

Create a trackable JavaScript or TypeScript module graph:

Use codex-tldraw to create a code graph for this repo.

After the code changes, compare it with the saved graph:

Use codex-tldraw to preview code graph drift, then mark stale elements.

The default outputs are:

<repo>/boards/main.tldr
<repo>/boards/main.svg

Open the .tldr board in a tldraw-compatible viewer to edit it. Any MCP host, browser, documentation system, or code review can display the .svg preview directly.

See the v0.6.0 release notes for compatibility and verification details.

What You Get

• A repo-local .tldr board that stays with the project it explains, plus a portable .svg preview.
• 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.
• Simple architecture diagrams showing the main flow first, with supporting services below it.
• A trackable JavaScript and TypeScript module/import graph with drift detection.
• Red markers for stale nodes and edges, orange markers for changed modules, and a report of new elements.
• 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 /boards/.tldr.
• draw_canvas: appends a prompt-provided workflow, state machine, architecture sketch, or plan to /boards/.tldr.
• draw_architecture: appends a simple codebase architecture view with a main flow, supporting components, actions, calls, and errors.
• diagramcodegraph: scans repository-local JavaScript and TypeScript modules and appends a trackable import graph.
• comparecodegraph: previews drift or marks changed and stale elements on an existing trackable code graph.
• list_boards: lists boards under a repo's boards/ directory.
• readboardsummary: summarizes generated diagrams and shape counts and returns both artifact paths.

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

Shortened. The full README is on GitHub.