TD MCP / TouchDesigner MCP

MCP server that bridges AI agents and TouchDesigner. One Node process speaks MCP over stdio (or HTTP); TouchDesigner runs a Python WebServer bridge that executes network operations.

Features

Targets and lifecycle

• list_td_targets / select_td_target — sticky multi-instance routing via tdmcp-hub
• create_td_project / start_td_project / stop_td_project — owned project lifecycle
• inject_td_mcp — adopt a foreign .toe for live MCP control
• td_ui_dialogs — list/dismiss Windows load dialogs on owned instances

Nodes and parameters

• get_td_nodes, create_td_node, delete_td_node
• get_td_node_parameters, update_td_node_parameters
• exec_node_method, get_td_node_errors

Python and visuals

• execute_python_script — run Python inside TouchDesigner
• get_top_image — capture a TOP as JPEG for visual verification

Offline .toe (ToeDigest)

• get_toe_digest — expand/cache a .toe on disk (stats, outline, wires, extensions, …)
• get_toe_node — deep inspect one node without opening TD

Help and meta

• get_td_info — identity and bridge status on the sticky target
• get_td_classes, get_td_class_details, get_td_module_help
• describe_td_tools — on-demand tool manifest with full Zod schemas

MCP prompts

Built-in prompts: node search, node connection, check node errors.

Quick start

git clone https://github.com/Verbalize-public/td-mcp.git
cd td-mcp
npm ci
npm run build

Wire your MCP client to dist/cli.js (see docs/installation.md). In TouchDesigner, use the project template via create_td_project or import td/mcp_webserver_base.tox for a lab bridge on port 9981.

Documentation

Doc	Topic
docs/installation.md	Prerequisites, TD setup, client configs
docs/development.md	Build, test, codegen, versioning
docs/architecture.md	Dual-process design, hub, transport
docs/hub.md	tdmcp-hub tunnel contract
docs/AGENT_MCP.md	Agent operations guide
docs/toe-digest.md	Offline .toe tools

Troubleshooting

Connection errors (ECONNREFUSED, …): TouchDesigner must be running with the MCP bridge active. Lab convention is WebServer on 9981; owned projects dial tdmcp-hub on 9980 via reverse tunnel. See docs/installation.md.

Version compatibility: MCP API version is declared in package.json (mcpCompatibility.minApiVersion). After changing tool schemas, run npm run build and restart the MCP client so it loads fresh dist/ output.

Issues: github.com/Verbalize-public/td-mcp/issues

Contributing

Pull requests welcome. Run npm run lint and npm run test:unit before submitting. Agent-facing contracts live in docs/AGENT_MCP.md.

License

MIT — see LICENSE.