td-mcp
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., "@td-mcp build a feedback loop using noise and a level TOP"
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.
td-mcp
A lean, token-efficient MCP server for driving TouchDesigner from AI assistants like Claude.
Build whole node networks in one call, search CHOP channels by glob, inspect operators compactly, and screenshot any TOP so the assistant can see what it built. Battle-tested by building audio-reactive and hand-tracking projects end to end.
Why another TouchDesigner MCP?
Compared to a conventional per-node tool surface, td-mcp is designed to minimize round trips and context tokens:
td_build- create a whole network (operators + parameters + expressions + wires) in ONE call.td_find_channels- glob-search every CHOP in the project (e.g.*pinch*) instead of dumping node trees.td_get- returns only NON-default parameters.td_screenshot- saves any TOP to PNG for visual verification.td_ensure_cook- one call installs a per-frame force-cook (fixes the classic "GLSL/feedback network renders once then freezes" gotcha).Wrong parameter names return close-match suggestions instead of bare errors.
Operator paths self-locate by name if the exact path moved.
One-line tool descriptions - tool schemas are loaded into every session, so short docs are cheaper.
Related MCP server: touchdesigner-mcp
Architecture
Claude / MCP client
| stdio (MCP)
server.py (Python, FastMCP)
| HTTP POST 127.0.0.1:9980/api (JSON)
TouchDesigner: /project1/td_mcp
|- webserver (Web Server DAT, port 9980)
|- callbacks (Text DAT - HTTP handler)
|- dispatcher (Text DAT - 16 command handlers, TD Python API)The bridge is installed by script (no .tox drag-drop): re-runnable, self-healing, and the DAT contents always match the repo sources.
Setup
Requirements: uv, TouchDesigner (any recent build; tested on 2025.3x macOS).
Clone and install:
git clone https://github.com/YOURNAME/td-mcp && cd td-mcp && uv syncInstall the bridge inside TouchDesigner - open the textport (Alt+T / Option+T) and run (adjust the path to your clone):
exec(open('/path/to/td-mcp/td/install_bridge.py').read())Verify from a terminal:
curl -s http://127.0.0.1:9980/api -d '{"cmd":"status"}'Register the server with your MCP client. For Claude Code, in
.mcp.json:{ "mcpServers": { "td": { "command": "uv", "args": ["--directory", "/path/to/td-mcp", "run", "python", "server.py"] } } }Restart the client and ask it to
td_status.
Tools
Tool | Purpose |
| TD + bridge status |
| whole network in one call (ops, params, exprs, wires) |
| single operator create / delete |
| set params; |
| wire two operators |
| compact inspection |
| glob-search CHOP channels project-wide |
| live channel values |
| per-frame force-cook (anti-freeze) |
| save a TOP to PNG |
| save project / load a .tox |
| all erroring operators under a path |
| escape hatch: run Python inside TD |
Field notes (learned the hard way)
TD's Python
open()defaults to ASCII - the bridge sources are pure ASCII.ParModeis not on thetdmodule inside DAT modules; the dispatcher usestype(par.mode).EXPRESSIONinstead (version-proof).Feedback TOPs need an actual input connection, not just a Target TOP.
COMP-to-COMP wiring requires matching connector families (a CHOP output cannot feed a DAT input) - check
outputConnectors[i].outOPtypes.After building feedback networks, pulse
resetpulseonce to flush any pre-expression frames the loop may have latched.
Credits
Bridge-over-Web-Server-DAT architecture inspired by 8beeeaaat/touchdesigner-mcp.
License
MIT
Available Tools
16 toolstd_buildA
Build a whole network in ONE call. ops: [{type:'circleTOP', name, params:{p:v or {expr:..}}, x, y}]. wires: [[from,to] or [from,to,to_in]] using op names or paths. Returns actual paths (TD may auto-rename).
Inputs: ops (required), parent (required), wires. Returns: result
td_connectC
Wire from_path output -> to_path input.
Inputs: to_path (required), from_path (required), to_in, from_out. Returns: result
td_createC
Create one operator; optional params applied atomically.
Inputs: type (required), x, y, name, +2 more. Returns: result
td_deleteC
Delete an operator.
Inputs: path (required). Returns: result
td_ensure_cookA
Install a per-frame force-cook on a node (fixes GLSL/feedback freeze).
Inputs: path (required). Returns: result
td_errorsC
All erroring ops under a path.
Inputs: depth, parent. Returns: result
td_execA
Escape hatch: run Python inside TD (op, project, ParMode, absTime in scope). Returns stdout.
Inputs: code (required). Returns: result
td_find_channelsA
Find CHOP channels by glob across the project (e.g. 'pinch'). Returns chop paths + matching channel names.
Inputs: pattern (required), limit, parent. Returns: result
td_getA
Inspect an op: type, errors, NON-DEFAULT params only, wiring, res/chans.
Inputs: path (required). Returns: result
td_listB
List child ops (family: TOP/CHOP/DAT/SOP/COMP).
Inputs: depth, limit, family, parent, +1 more. Returns: result
td_load_toxB
Load a .tox component into the project.
Inputs: file (required), parent. Returns: result
td_read_chopC
Current channel values of a CHOP (glob filter).
Inputs: path (required), channels. Returns: result
td_saveB
Save the .toe project (optionally to a new path).
Inputs: file. Returns: result
td_screenshotA
Save a TOP's image to PNG (default under td-mcp/shots) so the client can view it.
Inputs: top_path (required), file. Returns: result
td_setA
Set parameters. Value forms: 5, 'str', {'expr':'absTime.seconds'}, 'PULSE'. Unknown names return close-matches.
Inputs: path (required), params (required). Returns: result
td_statusA
TD + bridge status. Call first to verify the connection.
Inputs: no named parameters. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 16 tools
Each tool targets a distinct operation: status checks connection, build creates networks, create makes single ops, set modifies params, connect wires, get inspects, list enumerates children, delete removes, find_channels/read_chop handle CHOP data, ensure_cook forces cooking, screenshot captures images, save/load handle files, errors finds problems, and exec runs arbitrary Python. No two tools have overlapping purposes.
All tools follow a consistent `td_verb` or `td_noun` pattern, with verbs like create, set, connect, get, list, delete, find, read, save, load, and exec. The two noun-like names (td_status, td_errors) are intuitive and don't break the overall naming scheme.
16 tools is comprehensive but not excessive for a TouchDesigner MCP server that needs to support network building, parameter manipulation, inspection, debugging, file I/O, and execution. It's one tool over the typical '5-15' range but still well-scoped for the diversity of operations.
The tool set covers the core lifecycle: create, delete, connect, set params, save/load, and inspect. It also includes important extras like channel finding, error reporting, screenshots, and a Python escape hatch. Minor gaps exist (no explicit disconnect/rename/move operations), but td_exec can cover these, so agents have workarounds.
Maintenance
Related MCP Connectors
MCP server for Producer/Riffusion AI music generation
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
Make games with AI: one MCP server that connects your agent to Unity, Unreal and Godot editors.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Related MCP Servers
- AlicenseBqualityAmaintenanceA Model Context Protocol server that enables AI agents to control and operate TouchDesigner projects through creation, modification, and querying of nodes and project structures.141,267 npm638MIT
- AlicenseAqualityDmaintenanceAn MCP server for TouchDesigner that lets you control TouchDesigner with Claude5MIT
- 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
- AlicenseAqualityDmaintenanceMCP server for controlling TouchDesigner from AI coding agents like Claude Code and Codex CLI, enabling operator manipulation, parameter control, and screenshot capture.1214 PyPIMIT