TouchDesigner MCP

TouchDesigner MCP lets Codex inspect, build, wire, tune, sample, and visually verify a running TouchDesigner project. It is designed for generative visuals, audio-reactive systems, GLSL iteration, show-control networks, and fast agent-assisted prototyping.

The integration is local-first:

Codex / ChatGPT desktop / Codex CLI
          │ MCP over stdio
          ▼
  touchdesigner-mcp (Node.js)
          │ authenticated HTTP on 127.0.0.1
          ▼
 TouchDesigner Web Server DAT
          │ main-thread Python callbacks
          ▼
     your .toe network

What it can do

• Inspect networks, operators, parameters, wiring, cook times, warnings, and script errors.
• Create and connect COMP, TOP, CHOP, SOP, MAT, DAT, and POP operators.
• Set constant parameters, Python expressions, and bind expressions.
• Update GLSL/Text DAT source with optional compare-before-write protection.
• Build a reusable audio analysis rig with low, mid, high, level, and beat channels.
• Sample live CHOP values and return TOP captures as real MCP image content.
• Apply ordered edit batches with a best-effort TouchDesigner undo block.
• Run arbitrary TouchDesigner Python only when explicitly enabled on both sides.

The server uses the current split MCP TypeScript packages and serves both modern and legacy MCP clients through the SDK's stdio negotiation entry point.

Requirements

• TouchDesigner 2025 Official or newer. POP tooling requires a POP-capable build.
• Node.js 20 or newer.
• A local Codex client: ChatGPT desktop, Codex CLI, or the Codex IDE extension.

1. Install the TouchDesigner bridge

1. Clone this repository.
2. Drag touchdesigner/install_bridge.py into /project1 in TouchDesigner as a Text DAT.
3. Right-click the DAT and select Run Script.
4. Copy the printed URL and token. The default URL is http://127.0.0.1:9980.
5. Confirm http://127.0.0.1:9980/health returns JSON in a browser.

If TouchDesigner cannot find the sibling callback file, run this in the Textport with absolute paths:

installer = r"C:\path\to\touchdesigner-mcp\touchdesigner\install_bridge.py"
callbacks = r"C:\path\to\touchdesigner-mcp\touchdesigner\bridge_callbacks.py"
scope = {'__name__': 'touchdesigner_mcp_installer'}
exec(compile(open(installer, encoding='utf-8').read(), installer, 'exec'), scope)
scope['install'](callback_file=callbacks)

The installer creates /project1/touchdesigner_mcp_bridge, a loopback-only Web Server DAT, its callback DAT, and a random bearer token. Save the .toe after installation.

2. Build the MCP server

npm install
npm run build

From the repository root, confirm it starts:

$env:TOUCHDESIGNER_URL = 'http://127.0.0.1:9980'
$env:TOUCHDESIGNER_TOKEN = 'paste-token-here'
node dist/index.js

The process waits for MCP messages on stdin. Its readiness message is written to stderr so it never corrupts the MCP protocol stream.

3. Connect Codex

The supported CLI form is:

codex mcp add touchdesigner `
  --env TOUCHDESIGNER_URL=http://127.0.0.1:9980 `
  --env TOUCHDESIGNER_TOKEN=paste-token-here `
  -- node C:\absolute\path\to\touchdesigner-mcp\dist\index.js

Or add this to ~/.codex/config.toml (also available as examples/codex.config.toml):

[mcp_servers.touchdesigner]
command = "node"
args = ["C:/absolute/path/to/touchdesigner-mcp/dist/index.js"]
startup_timeout_sec = 15
tool_timeout_sec = 60
default_tools_approval_mode = "writes"

[mcp_servers.touchdesigner.env]
TOUCHDESIGNER_URL = "http://127.0.0.1:9980"
TOUCHDESIGNER_TOKEN = "paste-token-here"

Restart the local Codex client after adding the server, then use /mcp or codex mcp list to confirm it is enabled. The ChatGPT desktop app and Codex IDE extension also expose MCP server settings in their UI.

First session

Try this prompt:

Check TouchDesigner status. Inspect /project1, build an audio-reactive analysis rig, then create a feedback-based visual whose displacement follows low frequencies and whose color follows high frequencies. Check the network for errors and capture the final TOP so we can iterate visually. Do not delete existing operators.

Codex can use this verification loop:

1. td_status
2. td_list_operators and td_inspect_operator
3. td_build_audio_reactive_rig
4. td_batch for coherent graph creation and wiring
5. td_sample_chop to calibrate live ranges
6. td_get_errors
7. td_capture_top to evaluate the result visually

Tools

Tool	Purpose	Mutation
td_status	Bridge, build, project, timeline, capabilities	Read
td_list_operators	Bounded recursive network discovery	Read
td_inspect_operator	Parameters, wiring, cook data, errors	Read
td_create_operator	Create any supported OP type	Write
td_set_parameters	Constants, expressions, bind expressions	Write
td_pulse_parameter	Reset/open/clear-style actions	Write
td_connect / td_disconnect	Network wiring	Write
td_set_dat_text	GLSL, scripts, and callback source	Write
td_sample_chop	Live control/audio values	Read
td_capture_top	PNG/JPEG visual feedback	Read
td_get_errors	Errors, warnings, and script errors	Read
td_build_audio_reactive_rig	Standardized audio features	Write
td_batch	Up to 100 ordered graph edits	Write/destructive
td_delete_operator	Delete exactly one non-protected OP	Destructive
td_run_script	Arbitrary Python, opt-in only	Destructive

Audio-reactive design notes

td_build_audio_reactive_rig creates a source, full spectrum view, filtered low/mid/high RMS branches, a full-level RMS branch, a configurable beat gate, smoothing, and /OUT_AUDIO. Use the stable output Null in expressions and exports so downstream visuals survive internal changes.

Good mappings are usually nonlinear and smoothed:

• low: feedback displacement, scale, particle emission, camera kick.
• mid: geometry deformation, noise amplitude, line width, scene transitions.
• high: bloom, chromatic separation, color temperature, strobe accents.
• level: master intensity or a subtle breathing envelope.
• beat: threshold gate for cuts, triggers, and event-style accents.

Sample the live channels before choosing ranges. A Math CHOP or Function CHOP can normalize, clamp, ease, and shape response curves more reliably than hard-coded multipliers.

Safety model

• The bridge listens on 127.0.0.1 by default and uses a random bearer token.
• /health is the only unauthenticated route and exposes no project data.
• Request bodies, list sizes, batch sizes, and image sizes are bounded.
• /, /project1, the bridge itself, and its ancestors cannot be deleted.
• Arbitrary Python is absent from the MCP tool list unless TOUCHDESIGNER_ALLOW_SCRIPT=true; the TouchDesigner bridge must independently allow it.
• td_set_dat_text supports expectedText for optimistic concurrency.
• Batch rollback uses TouchDesigner's undo system and is best-effort; save/version important projects before large mutations.

Do not expose the Web Server DAT to another interface unless you add TLS, network controls, and an appropriate authentication design. Basic local bearer-token protection is not an internet-facing security boundary.

Configuration

Environment variable	Default	Meaning
TOUCHDESIGNER_URL	http://127.0.0.1:9980	Bridge base URL
TOUCHDESIGNER_TOKEN	empty	Bearer token printed by installer
TOUCHDESIGNER_TIMEOUT_MS	15000	Per-call timeout
TOUCHDESIGNER_ALLOW_SCRIPT	false	Advertise arbitrary Python tool
TOUCHDESIGNER_MAX_CAPTURE_BYTES	8000000	Maximum decoded TOP capture size

Development

npm run validate
npm run build
npm pack --dry-run

TouchDesigner-specific code is syntax-checked outside TouchDesigner, while its behavior must be integration-tested in a running licensed TouchDesigner process. The HTTP client and error handling have isolated unit tests.

See docs/architecture.md, docs/protocol.md, and CONTRIBUTING.md for extension guidance.

Sources and compatibility

This project follows the official Codex MCP configuration documentation, the official MCP TypeScript SDK server guide, and Derivative's Web Server DAT, Webserver DAT class, Connector class, and TOP capture APIs.

License

MIT