What is codex-tldraw MCP?
codex-tldraw-mcp is a stdio MCP server that scans a repository, infers its product workflow and writes an editable tldraw board plus an SVG preview into the project. It also builds a trackable JavaScript and TypeScript import graph, compares it for drift after changes, and draws prompt-driven diagrams and architecture sketches without scanning anything.
It is a stdio MCP server, built Codex-first, that turns a repository scan or a plain description into an editable tldraw board. The board and a portable SVG preview save into the repository itself, so the diagram stays with the project it explains.
What the tools do
- diagram_repo scans a repository and appends an inferred product workflow diagram to a named board.
- draw_canvas appends a prompt-provided workflow, state machine, architecture sketch or plan, with no repository scan involved.
- draw_architecture appends a simple codebase view: one main flow, supporting services below it, each step showing at most three actions and two short errors.
- diagram_code_graph scans local JavaScript and TypeScript modules and appends a trackable import graph as nodes and edges.
- compare_code_graph previews drift against a stored code graph, or applies markers for changed and stale elements.
- list_boards lists the boards saved under a repository.
- read_board_summary summarizes a board's diagrams and shape counts and returns both artifact paths.
Two ways to get a diagram
diagram_repo and diagram_code_graph read the actual repository. draw_canvas and draw_architecture take a written description instead and skip scanning entirely, so they work even against a plan that has no code yet.
Who codex-tldraw MCP is for
Best for
- Codex users who want a repository turned into a shareable product workflow diagram without hand-drawing it first.
- Teams tracking a JavaScript or TypeScript import graph across changes, where compare_code_graph flags stale and changed modules after a refactor.
- Anyone who wants a board that opens in any tldraw-compatible viewer, plus an SVG preview any MCP host or browser can render without one.
Not for
- When the need is a live interactive canvas for architecture diagrams with real AWS, Azure or GCP vendor icons, Excalidraw Icons MCP is the better fit for that canvas.
- When the task is loading general design guidelines for charts, mockups or SVG art on demand rather than scanning a real repository, Generative UI MCP is the better fit for that guidance.
- When the output wanted is an animated flow diagram rendered from plain English or Mermaid into one self-contained SVG, Dashmotion is the better fit for that animation.
- When the job is running a separate local desktop design editor beside the canvas with Codex attached, rather than writing boards from a repository scan, Figmaboy MCP is the better fit for that editor.
Connect codex-tldraw MCP: Repo-Scanned Workflow Diagrams to your AI client
codex mcp add codex-tldraw -- npx -y codex-tldraw-mcpAdd the server to Codex
Run codex mcp add codex-tldraw -- npx -y codex-tldraw-mcp. Codex starts the server over stdio on the next session.
Or edit the Codex config by hand
Add the TOML block above under mcp_servers in the Codex configuration, with command npx and args -y and codex-tldraw-mcp.
Use any other stdio MCP client
Point the client at command npx with args -y and codex-tldraw-mcp; the server speaks plain stdio outside the Codex plugin path too.
Restrict which repositories it can touch
Set TLDRAW_MCP_ALLOWED_ROOTS to a path-delimited allowlist, so repoPath must resolve inside one of those roots before a tool reads or writes anything.
Client configuration
[mcp_servers.codex-tldraw]
command = "npx"
args = ["-y", "codex-tldraw-mcp"]What you can do with it
- Repo-scanned workflow diagramsdiagram_repo infers the real product flow from the repository instead of a guess typed into a prompt.
- Prompt-driven diagrams toodraw_canvas draws a workflow, state machine or architecture sketch from a plain description, with no repository scan involved.
- Simple architecture viewdraw_architecture keeps the main flow in one row with supporting services below it, each step capped at three actions.
- Trackable code graphs with drift detectiondiagram_code_graph and compare_code_graph track import relationships across changes, marking stale and changed elements after a refactor.
- Non-destructive updatesA new diagram appends to the right of an existing board instead of overwriting what was already drawn.
- Portable SVG preview with every boardAny MCP host, browser or documentation system can show the SVG directly, with no tldraw viewer needed to see it.
- ETag-protected saves in the embedded editorThe Codex plugin's board editor blocks a stale save and offers a reload after a conflict, instead of overwriting silently.
Tools it exposes
diagram_repo
Scans a repository and appends an inferred product workflow diagram to a named board.
draw_canvas
Appends a prompt-provided workflow, state machine, architecture sketch or plan, without scanning the repository.
draw_architecture
Appends a simple codebase view with one main flow and supporting services, each limited to three actions and two short errors.
diagram_code_graph
Scans local JavaScript and TypeScript modules and appends a trackable import graph.
compare_code_graph
Previews drift against a stored code graph, or applies markers for new, changed and stale elements.
list_boards
Lists the boards saved under a repository.
read_board_summary
Summarizes a board's diagrams and shape counts and returns both artifact paths.
Frequently asked questions
What is codex-tldraw MCP?
It is a stdio MCP server, packaged as codex-tldraw-mcp, that scans a repository and writes an editable tldraw workflow board plus an SVG preview into the project. It also builds a trackable JavaScript and TypeScript import graph and can draw prompt-driven diagrams without scanning anything.
How do I install codex-tldraw MCP?
Run codex mcp add codex-tldraw -- npx -y codex-tldraw-mcp to register it with Codex over stdio. Any other stdio-capable MCP client can point its own configuration at command npx with args -y and codex-tldraw-mcp.
What tools does it expose?
Seven: diagram_repo and diagram_code_graph read the real repository; draw_canvas and draw_architecture take a written description instead; compare_code_graph checks drift on a stored code graph; list_boards and read_board_summary retrieve what has already been drawn.
Does it need a live browser canvas to work?
No. It is snapshot-only: it writes a .tldr board and an SVG preview into the repository rather than driving a live collaborative canvas. A tldraw-compatible viewer opens the board afterward, and the SVG renders anywhere without one.
How does code graph drift detection work?
diagram_code_graph stores a fingerprint for each source module as a node, with edges for imports, re-exports and require calls. compare_code_graph then marks each element unchanged, changed, stale or new against the stored version, and an apply flag updates the board's markers.
Can other MCP clients use it, not just Codex?
Yes. The standalone MCP tools speak plain stdio and accept an optional repoPath, so any MCP-compatible client can register command npx with args -y and codex-tldraw-mcp. The bundled plugin and its embedded board editor are Codex-specific.
What happens if two diagram calls target the same board?
Each gets appended to the right of what is already there rather than replacing it, and a per-board lock keeps simultaneous calls from different processes from corrupting the same board.
Can it restrict which repositories it reads or writes?
Yes. Setting the TLDRAW_MCP_ALLOWED_ROOTS environment variable to a path-delimited allowlist means the repoPath argument must resolve inside one of those listed roots before diagram_repo, draw_canvas or any other tool is allowed to touch a repository at all.