touchbridge
This server lets you control and monitor a TouchDesigner project over MCP: read and edit nodes/parameters, run batches, inspect data, manage the timeline, export renders, save snapshots, and operate a show-safe bridge with show mode and watchdog health checks.
Read and write nodes: create, delete (hidden in safe mode), copy, rename, find, list, get metadata, set flags, get errors, clear script errors, snapshot parameter states.
Parameter control: get/set values, read metadata, set expressions, pulse momentary parameters.
Wiring: create, delete, and inspect connections between operators.
Data access: read CHOP, TOP (optional PNG), SOP, and DAT content; write DATs; sample pixel luma statistics.
Scripting support: list td classes/modules, get class details and help; raw Python/eval only via bridge_send and gated by safe mode.
Timeline control: read/set cook rate, real-time flag, jump to frame, play/pause.
Rendering: screenshot a TOP, export frames to image files, export/import .tox components.
Project management: project info, safe incremental saves, snapshots, restore as new files, list versions.
Measurement and diagnostics: cook-time ranking, FPS/realtime, GPU stats, round-trip verify, full-network error sweeps, pixel analysis, chain topology/orphans.
Batch operations: execute multiple router requests in one round trip.
Layout: set node positions and align nodes.
Show mode: enforce a performance lock inside TD that allows reads plus allowlisted parameter changes, refusing structural/script/save operations; survives restarts and fails closed.
Watchdog/health: bridge status/state, bridge_health-equivalent checks for TD crashes, freezes, low FPS, long frame times, dropped frames, black/solid/frozen output.
Safety features: safe mode on by default removes destructive tools; saves never overwrite existing files; exports refuse .toe/.tox unless allowed; raw routes are gated.
Compact results: all tools accept YAML/JSON and detail levels (full/summary/minimal) to reduce tokens.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@touchbridge check GPU health and current FPS in the project"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
touchbridge
The TouchDesigner MCP you can leave connected during a show.
Most TouchDesigner MCP servers are built for working in the patch: a designer at the keyboard, TD mostly idle, an agent building networks. touchbridge is built for the moment the show is running: TD under full render load, a project file you can't lose, and an operator who needs to know the second something breaks.
touchbridge is the TouchDesigner control layer from ClipSense, a live-visuals system, pulled out into its own project. Every rule in it comes from a real failure on a real show.
What only touchbridge does
Show mode: a performance lock enforced inside TD. One call (or one command) locks the bridge: the agent can still read everything, and it can change only the parameters you allowlisted, e.g.
/project1/master:Opacity. Creating, deleting, wiring, scripting and saving are all refused by TD itself, so the lock holds for every client, not just this server. Leaving show mode takes the operator typingEND SHOW. The mode survives restarts.A show watchdog.
touchbridge-watch(or thebridge_healthtool) reports TD crashed, TD frozen, FPS below the cook rate, frame time over budget, dropped frames, and output black, solid or frozen. The numbers come from TD's own Perform CHOP.--reopenbrings the last saved.toeback up after a crash.No server inside TD. Commands are files. TD picks them up on a 0.1 s tick at its own pace (an idle tick costs 0.1 ms), and a busy TD answers late instead of dropping connections. A heartbeat tells busy from dead. Measured round trip: about 86 ms median.
It can't overwrite your project. Saves go to a new numbered
.toe. Snapshots copy files and never Save As. Exports refuse.toe/.toxtargets. Safe mode is on by default: delete, raw Python and in-place save are removed from the tool list, and the batch and raw routes are gated too.
And everything you'd expect
70 tools covering nodes, parameters, wiring, CHOP/TOP/SOP/DAT data, timeline,
render, project versions, batch, layout, and measurement (cook-time ranking,
GPU, pixel statistics, a full-network error sweep). Results come back as
compact YAML: about 30% fewer tokens than JSON with nothing lost, and about
80% fewer with detail="summary".
How it compares to the other TouchDesigner MCP servers, honestly: docs/COMPARISON.md.
Quickstart
1. Put the bridge in your project. Drag
touchdesigner/TouchBridge.tox (or get it from the
latest release) into any
TouchDesigner project and save. Nothing needs to be installed on the TD side;
the bridge code is embedded in the .tox. To try it right away, open
touchdesigner/TouchBridge.toe, which already has the .tox in it.
2. Install the MCP server (Python 3.11+). pipx puts touchbridge-mcp
on your PATH, where Claude Desktop and Cursor can find it:
pipx install "git+https://github.com/GaNotchVFX/touchbridge@v0.4.0"
# or: pip install "touchbridge @ git+https://github.com/GaNotchVFX/touchbridge@v0.4.0"If your client can't find the command, put the full path to
touchbridge-mcp (where touchbridge-mcp / which touchbridge-mcp) in
"command".
3. Point your MCP client at it. For Claude Desktop, Cursor, and anything
else that reads mcpServers:
{
"mcpServers": {
"touchbridge": { "command": "touchbridge-mcp" }
}
}That's it. Both sides default to the same bridge folder
(~/.touchbridge/bridge), so there's nothing to configure. Ask your agent to
run bridge_status; you should see alive: true.
Useful flags: --allow-destructive (turns off safe mode), --bridge-dir PATH
(or $TOUCHBRIDGE_DIR, set for both TD and the server), --format json,
--detail summary. See docs/MCP_REGISTRY.md for more
client configs.
Related MCP server: TDPilot
How it works
┌──────────────┐ commands/{id}.json ┌──────────────────────────────┐
│ MCP client │ ────────────────────────► │ TouchDesigner + TouchBridge │
│ (Claude, …) │ mode.json (show / prep) │ timer CHOP, every 0.1 s: │
│ touchbridge- │ │ show-mode gate, then run │
│ mcp (stdio) │ status.json (heartbeat) │ ≤4 queued commands; │
│ │ ◄──────────────────────── │ heartbeat + Perform stats │
└──────────────┘ results/{id}.json └──────────────────────────────┘TD pulls work; nothing is pushed into it. There's no listening socket and no request handler waiting on TD's main thread. Each tick picks up at most 4 commands, in arrival order, so a flood of calls can't pile into one frame (a single heavy command, such as a big
batch_executeor a full-project error sweep, still costs what it costs). If TD is slow, answers arrive later; nothing breaks.The heartbeat is the source of truth.
status.jsonis rewritten every tick.bridge_statereportsok,starting,down(TD running but not answering) oroff.One owner. With two TD instances open, exactly one services the queue (
owner.json). The claim hands over automatically when the owner goes quiet. This fixed a real incident where two instances were fighting over commands.Cost and speed, measured on TD 2025.32820 (Windows, NVIDIA) at 60 fps: an idle tick costs 0.1 ms of TD's frame, and FPS and frame time were unchanged with the bridge running. A round trip is 86 ms median (p90 125 ms).
measure_verifyreports yours asround_trip_ms. For 60 Hz streaming control, use OSC for that stream and touchbridge for everything else.
Show mode
touchbridge-mcp --set-mode show --allow "/project1/master:Opacity" --allow "/project1/fx*:Mix"
touchbridge-mcp --set-mode prep # operator ends the showOr from the agent: bridge_set_mode(mode="show", allow=[...]). Leaving from
the agent needs confirm="END SHOW", and the server tells the model that
phrase must come from the human.
In show mode | |
Always allowed | every read: nodes, params, CHOP/TOP/SOP/DAT data, errors, measure_*, read-only expressions |
Allowed if allowlisted |
|
Refused inside TD | create, delete, copy, rename, wire, flags, expressions, DAT writes, scripts, exports, timeline changes, saves, snapshots taken inside TD |
Refused by the server |
|
The mode is <bridge>/mode.json, read by TD on every tick. It survives
restarts, and an unreadable mode file counts as show, so the lock fails
closed. The allowlist can't be widened mid-show.
Watchdog
touchbridge-watch --output /project1/out1 # alerts on change, logs to <bridge>/watchdog.log
touchbridge-watch --output /project1/out1 --reopen # + reopen the last save if TD crashes
touchbridge-watch --once # one check; exit code 1 if anything is wrong21:54:03 ok fps 61.0/60.0 3.3 ms all clear(When something breaks, the line ends in ALERT: followed by the issues,
e.g. fps_low: 38.0 of 60; frame_time_high: 26.1 ms (budget 16.7 ms).)
It checks TD running / heartbeating (td_not_running, bridge_down), real
FPS vs cook rate, frame time vs budget, dropped frames, realtime off, and, with
--output, an output that's black, solid, or showing identical stats twice.
It never kills or restarts a TD that's still running; --reopen only acts
once the process is gone. The same snapshot is available to agents as
bridge_health.
Safety model
Guard | What it does |
Safe mode (default on) |
|
Never-overwrite saves |
|
Snapshots / restore |
|
Export guards |
|
Exec isolation |
|
Measure, don't assume | The server tells the model to confirm results by effect (read params back, |
What safe mode is and isn't. It's a guardrail against accidents: a confused agent can't delete a network, run a script, or save over your file with a single call. It is not a security boundary against an agent that's trying to get around it. Write-tier tools can still set Python parameter expressions or build an Execute DAT. If you don't trust the model or the prompt, don't connect it to a show machine.
The bridge folder is local: any process running as your user can drop commands in it, the same trust level as a localhost port. Don't share it over a network drive with people you don't trust.
Tools (70; 67 in safe mode)
Tool name = router method with . → _ (node.list → node_list).
◊ = destructive, hidden in safe mode.
system:
ping,infonode:
create,delete◊,list,get,copy,rename,find,set_flags,errors,errors_deep(subtree sweep: cook, warning, expression and script errors),clear_script_errors(tells a live problem from a stale one),snapshot(full param state to diff)par:
get,set,get_all,info,set_expression,pulseconn:
create,delete,get(plusconnection.*aliases)data:
chop,top(optional base64 PNG),sop,dat,dat_write,pixel_sample(luma mean/min/max/std with dark/solid/clipped flags)script:
exec◊,class_list,class_detail,module_helptimeline:
get,set,play,pauserender:
screenshot,exportproject:
info,save◊,snapshot,versions,import_tox,export_toxmeasure:
cooktimes(per-op cost, most expensive first),fps(FPS, realtime, throttle queue),gpu(NVIDIA util/VRAM measured host-side + "is TD really rendering"),verify(real round trip plus a live TD value),chain(Src/Srcpath topology and orphan detection for COMP chains that use those custom pars)batch:
execute(N ops in one round trip; not a rollback transaction)layout:
set_position,alignshow / health (host side):
bridge_mode,bridge_set_mode,bridge_healthbridge (host side):
bridge_status,bridge_state,bridge_save_increment,bridge_snapshot,bridge_snapshots,bridge_restore,bridge_ensure_alive,bridge_open_show,bridge_router_call,bridge_router_version,bridge_sendresources:
bridge://project,bridge://versions,bridge://snapshotsprompts:
diagnose_dark_output,wire_feedback_safely,save_before_editing
Compact results
Every tool accepts two optional arguments:
response_format:yaml(default) orjson. The YAML is lossless: it parses back to exactly the same data.detail:full(default),summary(lists cut to 25 items plus a... N moreline) orminimal(top-level values only; containers become<N items>). Long strings such as base64 images are never cut.
On sample payloads (80-parameter par_get_all, 120-child node_list), YAML is
about 30% smaller than the JSON the MCP SDK sends, and summary is 78–86%
smaller. Set server-wide defaults with --format / --detail or
$TOUCHBRIDGE_FORMAT / $TOUCHBRIDGE_DETAIL.
Development
pip install -e ".[dev]"
python -m pytest # 195 tests, no TouchDesigner neededThe router runs against a mock op graph, the file-bridge transport runs the
real poll loop in a thread, and the .tox bodies run against a mock COMP.
Rebuild TouchBridge.tox after changing bridge_logic.py or
command_router.py. In TD's Textport (Alt+T):
TB_REPO = r"C:\path\to\touchbridge"
exec(open(TB_REPO + "/tools/build_touchbridge_tox.py").read())Then run python tools/verify_touchbridge.py against real TD. It checks the
heartbeat, a node_get round trip, round-trip timing and the router version. For a live-edit
loop without rebuilding, set TOUCHBRIDGE_PKG=<repo>/touchbridge on the
process that launches TD; the .tox then loads the .py files from disk.
touchbridge/
command_router.py in-TD router: 56 handlers (node/par/data/measure/…)
bridge_logic.py in-TD poll loop, show-mode gate, heartbeat, owner claim
client.py host-side client (send, save_increment, snapshots)
mcp_server.py MCP server: tool catalog, safe-mode gating, resources
watch.py touchbridge-watch: the show watchdog
formatting.py compact YAML / detail shaping
tools/build_touchbridge_tox.py builds the self-contained TouchBridge.tox
touchdesigner/ TouchBridge.tox, example TouchBridge.toe, usage notes
tools/verify_touchbridge.py live post-install checkStatus and limits
Developed and used on Windows with current TouchDesigner builds. Nothing in the code is Windows-only, but macOS hasn't been tested yet; reports are welcome.
GPU stats need an NVIDIA GPU (
nvidia-smi). Everything else is vendor-neutral.The live-TD integration check is manual (
tools/verify_touchbridge.py): TouchDesigner has no headless mode for CI.Roadmap: PLAN.md. Changes: CHANGELOG.md.
License
MIT; see LICENSE.
Available Tools
67 toolsbatch_executeA
Run a list of router requests in ONE bridge round trip (transport batching, not a rollback transaction: failures are reported per item).
ops (list[typing.Any]): [{method, params}, ...] — the ops to run.
abort_on_error (bool | None): Stop at the first failure (default false).
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: ops (required), detail, abort_on_error, response_format.
bridge_ensure_aliveA
Open the show in TD (if needed) and wait for the bridge heartbeat. Returns alive status.
timeout (float | None): Max seconds to wait (default 45).
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: detail, timeout, response_format.
bridge_healthA
Show health in one call: bridge alive / TD frozen / TD gone, REAL fps vs cook rate, frame time vs budget, dropped frames, GPU memory/temp (TD's Perform CHOP), mode, and optionally whether an output TOP is black or solid.
output (str | None): TOP path of the show output to check for black/solid.
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: detail, output, response_format.
bridge_modeA
Current bridge mode: prep (normal editing) or show (live performance lock: reads + allowlisted params only), with the allowlist and since-when.
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: detail, response_format.
bridge_open_showA
Launch the resolved show .toe in TouchDesigner (refuses if TD is already running unless force).
force (bool | None): Launch even if TD is running.
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: force, detail, response_format.
bridge_restoreA
Restore a backup into the show folder as a NEW restored..toe sibling (never overwrites the live file).
backup (<class 'str'>): Absolute path to a backup .toe.
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: backup (required), detail, response_format.
bridge_router_callA
Raw router call for ANY router method (escape hatch; prefer the typed tools). Destructive methods stay gated by safe mode.
method (<class 'str'>): Router method name (e.g. 'node.get').
params (dict[str, typing.Any]): Method parameters as a dict.
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: method (required), detail, params, response_format.
bridge_router_versionA
Router surface version + method count (capability negotiation; soft-warn on mismatch, never hard-lock).
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: detail, response_format.
bridge_save_incrementA
SAFE save: write the next numbered Show.<N+1>.toe and structurally refuse to overwrite an existing file. The preferred way to persist bridge edits.
timeout (float | None): Seconds to wait (default 45).
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: detail, timeout, response_format.
bridge_sendA
Raw bridge send: op + payload. In safe mode only catalogued non-destructive router methods pass; the raw python/eval opcodes need --allow-destructive.
op (<class 'str'>): Bridge opcode (eval, python, ...).
payload (dict[str, typing.Any]): Payload dict.
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: op (required), detail, payload, response_format.
bridge_set_modeA
Enter SHOW mode (lock the bridge for a live performance: reads and the allowlisted parameters only; enforced inside TD for every client) or return to PREP. Leaving show mode needs confirm='END SHOW' TYPED BY THE HUMAN OPERATOR: never supply it on your own initiative.
mode (<class 'str'>): 'show' or 'prep'.
allow (list[str]): Entering show: params that may still change, as '/path:ParName' globs (e.g. '/project1/master:Opacity', '/project1/fx*:Mix').
confirm (str | None): Leaving show: the exact phrase END SHOW, from the operator.
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: mode (required), allow, detail, confirm, +1 more.
bridge_snapshotA
Copy the current show .toe to a timestamped backup (never overwrites anything).
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: detail, response_format.
bridge_snapshotsA
List existing backups, newest-first.
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: detail, response_format.
bridge_stateB
TD three-state probe: ok | starting | down | off.
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: detail, response_format.
bridge_statusA
Bridge heartbeat state: alive, age (s), project, build.
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: detail, response_format.
conn_createA
Wire two ops together (output -> input).
fromPath (<class 'str'>): Source operator path.
toPath (<class 'str'>): Destination operator path.
fromOutput (int | None): Source output index (default 0).
toInput (int | None): Destination input index (default 0).
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: toPath (required), fromPath (required), detail, toInput, +2 more.
conn_deleteB
Disconnect an input and/or output of a node.
path (<class 'str'>): Operator path.
inputIndex (int | None): Disconnect this input.
outputIndex (int | None): Disconnect this output.
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: path (required), detail, inputIndex, outputIndex, +1 more.
connection_createB
Alias of conn.create (kept for MCP-side compat).
fromPath (<class 'str'>): Source operator path.
toPath (<class 'str'>): Destination operator path.
fromOutput (int | None): Source output index (default 0).
toInput (int | None): Destination input index (default 0).
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: toPath (required), fromPath (required), detail, toInput, +2 more.
connection_deleteB
Alias of conn.delete.
path (<class 'str'>): Operator path.
inputIndex (int | None): Disconnect this input.
outputIndex (int | None): Disconnect this output.
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: path (required), detail, inputIndex, outputIndex, +1 more.
connection_getD
Alias of conn.get.
path (<class 'str'>): Operator path.
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: path (required), detail, response_format.
conn_getA
Read all input/output connections of a node.
path (<class 'str'>): Operator path.
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: path (required), detail, response_format.
data_chopA
Read CHOP channel values (uniformly downsampled).
path (<class 'str'>): CHOP operator path.
max_samples (int | None): Max samples per channel (default 1024).
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: path (required), detail, max_samples, response_format.
data_datA
Read text or table DAT content.
path (<class 'str'>): DAT operator path.
row_start (int | None): First table row (default 0).
row_end (int | None): Last table row, exclusive.
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: path (required), detail, row_end, row_start, +1 more.
data_dat_writeA
Write text / append a row / clear a DAT.
path (<class 'str'>): DAT operator path.
text (str | None): Replace full text content.
appendRow (list[typing.Any]): Append a row to a table DAT.
clear (bool | None): Clear before writing.
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: path (required), text, clear, detail, +2 more.
data_pixel_sampleA
Luma statistics of a TOP (mean/min/max/std) with dark / solid / clipped flags. The 'is the output actually black?' verifier.
path (<class 'str'>): TOP operator path.
grid (int | None): Samples per axis (default 16).
numpy (bool | None): Full-frame read via numpyArray().
dark_below (float | None): Mean luma below this = dark (0.02).
solid_std (float | None): Std below this = solid (0.005).
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: path (required), grid, numpy, detail, +3 more.
data_sopA
SOP point count/positions and bounds.
path (<class 'str'>): SOP operator path.
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: path (required), detail, response_format.
data_topA
TOP resolution, optionally base64 PNG pixel capture.
path (<class 'str'>): TOP operator path.
pixels (bool | None): Capture pixels as base64 PNG.
max_width (int | None): Downscale if wider (default 512).
max_height (int | None): Downscale if taller (default 512).
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: path (required), detail, pixels, max_width, +2 more.
layout_alignA
Distribute nodes along a horizontal or vertical axis.
paths (list[str]): Ordered operator paths.
axis (str | None): 'horizontal' (default) or 'vertical'.
start_x (float | None): X of the first node.
start_y (float | None): Y of the first node.
spacing (float | None): Gap between centres (default 200).
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: paths (required), axis, detail, spacing, +3 more.
layout_set_positionA
Set network-editor position of one or more nodes.
nodes (list[typing.Any]): [{path, x, y}, ...].
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: nodes (required), detail, response_format.
measure_chainA
Per-device topology: Bypass/Src/Srcpath truth + chain orphan detection for chained COMPs.
path (str | None): Root container to scan (default '/').
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: path, detail, response_format.
measure_cooktimesA
Per-operator cook cost (ms) sorted most-expensive first: which device is eating the frame.
paths (list[str]): Operator paths to measure.
path (str | None): Parent whose children are measured.
top (int | None): Return only the N most expensive.
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: top, path, paths, detail, +1 more.
measure_fpsC
FPS, realtime flag, cook rate, throttle queue.
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: detail, response_format.
measure_gpuA
GPU util/VRAM (NVIDIA, measured host-side so TD never blocks) + whether TD is really rendering. The 'looks healthy but isn't' detector.
require_render (bool | None): Error instead of returning empty stats when TD is not rendering and no GPU numbers are available (default false).
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: detail, require_render, response_format.
measure_verifyA
Round-trip canary over the file bridge: rtt_ms + a live TD value (absTime.seconds by default).
expr (str | None): Expression to eval (default absTime.seconds).
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: expr, detail, response_format.
node_clear_script_errorsA
Clear a node's accumulated script-error log, force a cook, re-read. recurring: true is proof of a LIVE problem; a one-off hit was stale.
path (<class 'str'>): Operator path.
force_cook (bool | None): cook(force=True) after clearing (default true).
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: path (required), detail, force_cook, response_format.
node_copyA
Copy a node into a destination parent.
sourcePath (<class 'str'>): Path of the operator to copy.
destParentPath (<class 'str'>): Destination parent COMP path.
name (str | None): Name for the copy; TD assigns if omitted.
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: sourcePath (required), destParentPath (required), name, detail, +1 more.
node_createB
Create an operator in a parent COMP (e.g. 'noiseCHOP'). Auto-placed to the right of siblings.
parentPath (<class 'str'>): Full path of the parent COMP.
type (<class 'str'>): Operator type string (e.g. 'noiseCHOP').
name (str | None): Desired name; TD assigns one if omitted.
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: type (required), parentPath (required), name, detail, +1 more.
node_errorsA
Errors/warnings for a node, optionally including children.
path (<class 'str'>): Full path of the operator.
includeChildren (bool | None): Also collect child errors.
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: path (required), detail, includeChildren, response_format.
node_errors_deepA
Walk a whole subtree; report every node with cook errors, warnings, parameter-expression errors or script errors. Only nodes with a problem are returned.
path (str | None): Root of the walk (default '/project1').
max_depth (int | None): Recursion limit (default 32).
max_nodes (int | None): Visit cap (default 5000).
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: path, detail, max_depth, max_nodes, +1 more.
node_findA
Search for nodes matching name/type/family, recursively.
path (str | None): Root container to search (default '/').
name (str | None): Case-insensitive substring on node name.
type (str | None): Exact operator type (case-insensitive).
family (str | None): 'CHOP'/'TOP'/'DAT'/'SOP'/...
depth (int | None): Max recursion depth (default 5).
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: name, path, type, depth, +3 more.
node_getA
Full metadata for one operator (params, connections, position).
path (<class 'str'>): Full path of the operator.
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: path (required), detail, response_format.
node_listA
List children of a container, optionally filtered by family.
path (str | None): Parent container path (default '/').
family (str | None): Filter by operator family (CHOP/TOP/...).
depth (int | None): Recursion depth; 1 = direct children.
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: path, depth, detail, family, +1 more.
node_renameA
Rename a node.
path (<class 'str'>): Full path of the operator.
name (<class 'str'>): New name for the operator.
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: name (required), path (required), detail, response_format.
node_set_flagsB
Set display / render / bypass flags on a node.
path (<class 'str'>): Full path of the operator.
display (bool | None): Set display flag.
render (bool | None): Set render flag.
bypass (bool | None): Set bypass flag.
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: path (required), bypass, detail, render, +2 more.
node_snapshotA
Complete parameter state (value/mode/expr/evalError) + flags, optionally written to a JSON file (never overwrites). Diff two snapshots around a risky edit.
path (<class 'str'>): Operator path.
out (str | None): JSON file under the project folder.
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: path (required), out, detail, response_format.
par_getA
Read parameter values, optionally filtered by glob.
path (<class 'str'>): Operator path.
pattern (str | None): Glob like 't[xyz]'; None = all.
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: path (required), detail, pattern, response_format.
par_get_allA
Full metadata (mode, bounds, menu names) for every par.
path (<class 'str'>): Operator path.
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: path (required), detail, response_format.
par_infoA
Metadata for named parameters (or all if names omitted).
path (<class 'str'>): Operator path.
names (list[str]): Parameter names; None = all.
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: path (required), names, detail, response_format.
par_pulseA
Pulse a momentary parameter.
path (<class 'str'>): Operator path.
name (<class 'str'>): Parameter name.
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: name (required), path (required), detail, response_format.
par_setA
Set one or more parameter values on an operator.
path (<class 'str'>): Operator path.
values (dict[str, typing.Any]): Mapping of parameter name -> value.
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: path (required), values (required), detail, response_format.
par_set_expressionC
Put a parameter into expression mode.
path (<class 'str'>): Operator path.
name (<class 'str'>): Parameter name.
expression (<class 'str'>): Python expression string.
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: name (required), path (required), expression (required), detail, +1 more.
project_export_toxA
Save a COMP to a .tox. Never a .toe; never overwrites unless overwrite=true.
path (<class 'str'>): COMP operator path.
out (<class 'str'>): Destination .tox under the project folder.
overwrite (bool | None): Allow replacing an existing file.
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: out (required), path (required), detail, overwrite, +1 more.
project_import_toxA
Load a .tox into a parent COMP. Path must be under the project folder or $TOUCHBRIDGE_TOX_ROOTS; .toe refused.
path (<class 'str'>): The .tox file.
parentPath (str | None): COMP to load into (default '/project1').
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: path (required), detail, parentPath, response_format.
project_infoA
Project + app metadata (name, folder, version, cook rate).
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: detail, response_format.
project_snapshotA
Save a timestamped, collision-free backup .toe.
dest (str | None): Backup folder; 'snapshots/' next to the project.
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: dest, detail, response_format.
project_versionsA
List saved .toe versions in the project folder, newest-first.
folder (str | None): Folder to scan (default project folder).
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: detail, folder, response_format.
render_exportB
Export a TOP frame to a file (extension picks format).
path (<class 'str'>): TOP operator path.
save_path (<class 'str'>): Output path (.png/.jpg/.exr...).
quality (int | None): JPEG quality 0-100 (default 90).
overwrite (bool | None): Replace an existing file (default false; .toe/.tox never).
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: path (required), save_path (required), detail, quality, +2 more.
render_screenshotA
Save a TOP's current frame to a PNG file.
path (<class 'str'>): TOP operator path.
save_path (str | None): Output PNG path; tempfile if omitted.
overwrite (bool | None): Replace an existing save_path (default false; .toe/.tox never).
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: path (required), detail, overwrite, save_path, +1 more.
script_class_detailA
Methods/properties/docstring for a td class.
name (<class 'str'>): Class or attribute name.
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: name (required), detail, response_format.
script_class_listA
List names in the td module (optional substring filter).
pattern (str | None): Case-insensitive substring.
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: detail, pattern, response_format.
script_module_helpA
help() output for a td name.
name (<class 'str'>): Name to look up.
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: name (required), detail, response_format.
system_infoA
TD version, cook rate, realtime flag and the full registered method list.
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: detail, response_format.
system_pingA
Liveness canary. Returns pong + TD frame.
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: detail, response_format.
timeline_getB
Current timeline / playback state.
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: detail, response_format.
timeline_pauseB
Pause timeline playback.
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: detail, response_format.
timeline_playA
Start timeline playback.
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: detail, response_format.
timeline_setA
Set cookRate, realTime and/or jump to a frame.
cookRate (float | None): Desired cook rate (fps).
realTime (bool | None): Enable/disable real-time playback.
frame (int | None): Jump to this absolute frame.
detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).
response_format (str | None): yaml (default, token-cheap) | json.
Inputs: frame, detail, cookRate, realTime, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 67 tools
There are several pairs of tools with overlapping purposes: node_get vs node_snapshot (both read node state), par_get vs par_info vs par_get_all (all read parameter info), and the connection_* aliases duplicate conn_* tools. However, many tools have distinct purposes (node_create vs node_copy vs node_rename). The presence of aliases and similar read endpoints creates some ambiguity.
The naming is mostly consistent with verb_noun pattern (e.g., node_get, par_set, data_chop), but there are deviations: some tools use 'get' (node_get) while others use 'list' (node_list), and the use of 'connection_*' aliases alongside 'conn_*' breaks consistency. Also, 'par_get_all' versus 'par_info' are not clearly differentiated by name.
With 57 tools, this is far beyond the typical 3-15 range and even exceeds the 25+ threshold. The server covers a broad domain (TouchDesigner automation), but many tools are highly specialized (e.g., measure_chain, data_pixel_sample) and could be consolidated. The count feels overwhelming and undermines usability.
The tool surface is quite comprehensive: it covers node CRUD (create, copy, rename, delete? no delete but set_flags), parameter operations (get, set, expression, pulse), connections, data reading for all families, timeline control, rendering, project save/restore, and performance measurement. Minor gaps include no explicit node delete or connection listing beyond conn_get, but the breadth is strong.
Maintenance
Related MCP Connectors
OSC ↔ MIDI bridge for synthesizers and DAWs, with the SynthHub catalogue. A MIDI MCP and OSC MCP.
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
Create, co-edit, analyze, publish, and export collaborative step-sequencer sessions through MCP.
One OAuth connector for your team's remote MCP servers, with Tool Packs, guardrails and logs.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceHigh-performance MCP server that enables AI assistants to control TouchDesigner live via WebSocket, providing 37 tools for nodes, parameters, scripting, and more.5MIT
- AlicenseBqualityBmaintenanceAn MCP server for TouchDesigner that lets AI agents inspect, build, wire, optimize, and stabilize live TD networks with 106 tools, plus a technique memory system for reusable patterns.11417MIT
- AlicenseNot gradedqualityCmaintenanceMCP server + web dashboard for TouchDesigner. Inspect, optimize, and control TD patches from Claude Code or the browser.MIT
- FlicenseBqualityDmaintenanceEnables control of a running TouchDesigner instance via MCP protocol, providing tools to manage operators, parameters, and project state through a local HTTP bridge.161-