Control TouchDesigner with AI Agents

TouchDesigner MCP bridges AI models and the TouchDesigner WebServer DAT, letting AI agents create, modify, and delete nodes, query node properties and project structure, and control TouchDesigner programmatically via Python scripts - effectively giving an assistant hands-on access to a live TouchDesigner project.

It exposes 12 tools: create_td_node and delete_td_node for node lifecycle management; exec_node_method for calling a Python method on a node and execute_python_script for running arbitrary Python inside TouchDesigner; get_module_help and get_td_class_details for retrieving Python help() documentation and class/module details; get_td_classes for listing available TouchDesigner Python classes; get_td_info for server environment information; get_td_node_errors for checking errors on a node and its children; get_td_node_parameters and update_td_node_parameters for reading and writing a node's parameters; and get_td_nodes for listing nodes under a parent path with optional filtering. Three prompts add higher-level guidance: "Search node" fuzzy-searches nodes by name, family, or type; "Node connection" gives instructions for wiring nodes together; and "Check node errors" recursively checks a node and its children for errors. Resources are not implemented.

The project takes compatibility seriously: the MCP server and the TouchDesigner-side API server use semantic versioning with explicit rules - matching MAJOR version and an API version at or above the minimum compatible version runs normally; a MINOR/PATCH mismatch within the same MAJOR version shows a warning but continues; and a MAJOR version mismatch or an API server below the minimum compatible version stops execution entirely until updated, since it signals breaking changes.

Connection troubleshooting is also built in: the TouchDesignerClient caches failed connection checks for 60 seconds to avoid spamming TouchDesigner with retries, and automatically clears the cache and re-verifies once the underlying issue is fixed. Guided error messages map specific error codes to fixes - ECONNREFUSED means TouchDesigner or its WebServer DAT (from mcp_webserver_base.tox) isn't running or the port (default 9981) is wrong; ETIMEDOUT points to a slow or blocked network requiring a TouchDesigner/WebServer DAT restart; and ENOTFOUND flags an invalid hostname, with 127.0.0.1 recommended unless explicitly changed.

Use this connector when you want an AI agent to inspect, modify, or script a live TouchDesigner project - creating or deleting nodes, reading or updating parameters, running Python scripts, or diagnosing node errors - rather than manually clicking through the TouchDesigner UI. Always match MCP server and TouchDesigner-side API server versions within the same MAJOR release; a mismatch across MAJOR versions is a hard stop by design, not a bug to work around.

Accepts tool calls specifying node paths, Python scripts, or parameter updates. Returns node data, class/module documentation, error reports, or the results of executed Python scripts and method calls against the live TouchDesigner project, connecting through TouchDesigner's WebServer DAT component (mcp_webserver_base.tox) with structured error logging through ILogger for diagnosing connection failures via the MCP logs.

The project is distributed as the touchdesigner-mcp-server npm package, but the README does not give a literal install command - it points to a separate Installation Guide (docs/installation.md) for setup, and to the Latest Release notes for update procedures. Setup requires placing mcp_webserver_base.tox in the TouchDesigner project with its WebServer DAT running on the configured port (default 9981), and matching the MCP server and TouchDesigner-side API server versions within the same MAJOR release. If a version mismatch causes a compatibility error, download the latest touchdesigner-mcp-td.zip from the releases page, replace the existing touchdesigner-mcp-td folder, and re-import the .tox into the TouchDesigner project's mcp_webserver_base component. Developer-facing setup (local development, client configuration, project structure) is covered separately in the Developer Guide.

TouchDesigner artists and developers who want an AI agent to build, inspect, or debug TouchDesigner node networks programmatically, including running arbitrary Python scripts inside a live project.