TD-Codex Ultimate MCP

An MCP server for TouchDesigner. It lets Claude Code, Codex, Cursor, VS Code and other MCP clients inspect and build networks in a running TouchDesigner session.

It has two parts:

Connect your client to the hub to get everything, or straight to the bridge for just the td_* tools.

Quick start

Requirements: TouchDesigner 2025 or later, Node.js 18 or later.

1. Start the bridge in TouchDesigner

1. Drag td-bridge/TD_mcp.tox into your project.

2. On the COMP's TD_mcp page, set Modules Folder to this repo's td-bridge/modules folder. You can leave it empty if the .tox is loaded as an external tox from td-bridge/, or if the modules folder sits next to your .toe.

3. Check the bridge is up:

   curl http://127.0.0.1:5326/health
   # {"status": "ok", "modules": ".../td-bridge/modules", "error": null}
   

The COMP has Port (default 5326) and Active parameters. If the bridge can't start, /health returns the Python traceback.

To build the bridge by hand instead: create a Web Server DAT and set its Callbacks DAT to a Text DAT holding td-bridge/modules/mcp_webserver_script.py. The modules folder is found from (in order) the TD_MCP_MODULES environment variable, a Modulesfolder parameter on the parent COMP, the callbacks DAT's synced file location, the external .tox location, and the project folder.

2. Start the hub

cd packages/mcp-server
npm install
npm start

The hub starts and accepts MCP connections even while TouchDesigner is down: the bridge tools appear once TD is reachable, and tool calls that need TD return an error result until then.

3. Connect a client

The .mcp.json at the repo root points MCP clients at the hub:

{ "mcpServers": { "td-codex": { "type": "http", "url": "http://127.0.0.1:3000/mcp" } } }

For Claude Code from anywhere: claude mcp add --transport http td-codex http://127.0.0.1:3000/mcp

Tools

Bridge tools (td_*, 68)

Live operator control (td_create_node, td_connect_nodes, td_set_node_parameter, td_exec_python_script, ...), DAT text, Python class/module help, operator and palette reference, snapshots and .tox export, scene/layout validation, release packaging, and curated knowledge, rule and workflow packs. Call td_get_connection_protocol first: it returns the rules the bridge expects agents to follow.

Hub tools (43)

Not supported: VITC timecode (TD has no VITC operator), decoding incoming MTC (needs a script), and Notch / Disguise (they need proprietary SDKs).

REST

Every tool is also available as POST /tools/<toolName> with the arguments as the JSON body. The older paths (/vision/capture-screenshot, /showcontrol/create-artnet-output, /media/connect-millumin, ...) and POST /mcp/creative-prompt still work. GET /health reports hub and TD status.

Tests

The TD tests only create operators under /td_mcp_test and delete them afterwards.

Notes

• The bridge's Python packages are called td_mcp and td_mcp_utils, not mcp/utils, so they don't shadow the official mcp SDK that other tools (e.g. Envoy) load into the same TouchDesigner process.
• td_exec_python_script runs in a fresh namespace with TouchDesigner's names (op, noiseTOP, absTime, ...). Set result = ... to return data. Scripts that create operators get a layout validation report for what they created.
• packages/embedded-mcp-server/, td_codex_ultimate_production_patch/, the root examples/ and SUMMARY.md / IMPLEMENTATION_SUMMARY.md describe older designs (WebSocket server on 8765, bridge on 9980). They are not part of the supported setup above.

License

MIT