touchdesigner-mcp: driving TouchDesigner from an AI agent over MCP

What touchdesigner-mcp actually connects

TouchDesigner has no built-in way for a language model to reach into a running project. You can write Python inside TouchDesigner, and you can drive it over its network interfaces, but neither gives an agent a structured list of operations it can call. This project fills that gap with a Model Context Protocol server: an npm package that exposes TouchDesigner operations as MCP tools, and a TouchDesigner component (a .tox file) that runs a WebServer DAT to receive them.

The audience is narrow and specific. It is for people who already build in TouchDesigner and want an agent such as Claude Desktop or a Codex-style client to create nodes, read parameters, inspect errors or run Python on their behalf. It is not a general TouchDesigner library, and it does not render anything on its own. Everything it does happens inside a TouchDesigner instance that is already open.

The bridge: MCP tools on one side, a WebServer DAT on the other

The README describes the server as a bridge between AI models and the TouchDesigner WebServer DAT. Two processes sit on either side of that bridge, and they are versioned separately.

The MCP side is the TypeScript server, published as touchdesigner-mcp-server. It registers a fixed set of tools with the client. Fourteen are listed: create_td_node, delete_td_node, describe_td_tools, exec_node_method, execute_python_script, get_td_class_details, get_td_classes, get_td_info, get_td_module_help, get_td_node_errors, get_td_node_parameters, get_td_nodes, get_top_image and update_td_node_parameters. The set is broad enough to be useful and narrow enough to reason about: node CRUD, parameter reads and writes, class and module introspection, error checks that recurse into children, and TOP image capture.

Three prompts ship alongside the tools: Search node, Node connection and Check node errors. Prompts are instructions rather than actions, so they shape how an agent approaches a task instead of performing it. The README states that resources are not implemented, which means there is no MCP resource layer to browse project state; everything goes through tool calls.

The TouchDesigner side is the mcp_webserver_base component imported from touchdesigner-mcp-td.zip. The default port is 9981. The client caches failed connection checks for 60 seconds, so a burst of tool calls after TouchDesigner goes down reuses one cached error instead of hammering the port, and it retries automatically once that TTL expires.

Installing the server and running a first node creation

The README does not inline the install steps. It points to docs/installation.md in the repository and, for upgrades, to the notes attached to the latest release. The npm package is touchdesigner-mcp-server, the binary it installs is touchdesigner-mcp-server, and package.json requires Node 20 or newer.

There is also a Docker path. The repository ships a Dockerfile built on node:24-slim that runs npm ci, then npm run build, then ./docker/start.sh, and a docker-compose.yml that maps the MCP inspector ports 6274 and 6277 plus a Streamable HTTP port that defaults to 6280. The compose file binds that HTTP port to loopback by default and sets TD_HOST to http://host.docker.internal with TD_PORT 9981, which is how a container reaches TouchDesigner running on the host.

npm install -g touchdesigner-mcp-server

That installs the CLI globally. The compose file shows the environment variables the server reads when it runs in a container, and the same names are the ones to check when debugging a connection.

environment:
  - TRANSPORT=${TRANSPORT:-manual}
  - MCP_HTTP_PORT=${MCP_HTTP_PORT:-6280}
  - MCP_HTTP_HOST=${MCP_HTTP_HOST:-0.0.0.0}
  - TD_HOST=${TD_HOST:-http://host.docker.internal}
  - TD_PORT=${TD_PORT:-9981}

On the TouchDesigner side, the sequence the README gives for resolving compatibility problems is also the cleanest description of a first install: download touchdesigner-mcp-td.zip from the releases page, extract it, import the .tox into your project, then restart TouchDesigner and the agent client. Once both sides are up, a first useful call is get_td_info, which reports the server environment and confirms the bridge is live before you ask for anything that mutates the project.

The version contract is the real adoption cost

Most of the friction in this project is not installation, it is version matching. The npm package version and the API version are independent axes. The API version is the contract between the server and the .tox component, and package.json declares both ends: minApiVersion 1.3.0 and expectedApiVersion 1.5.0.

The README is explicit that the npm package version never gates compatibility, which is a genuinely helpful design choice: updating the server alone will not invalidate a component you already have. What does gate it is the component's API version. An exact match works silently. A component at or above the minimum but below expected produces an update-recommended notice appended to responses and keeps going. A newer component on the same major version warns you to update the server and keeps going. A component on a higher major version, or one below the minimum, stops execution outright.

That last case is the failure mode to plan for. Execution stops, and the fix is manual: download the latest touchdesigner-mcp-td.zip, delete the existing touchdesigner-mcp-td folder, replace it with the extracted contents, remove the old mcp_webserver_base component from the project, import the new .tox, and restart both TouchDesigner and the agent. There is no in-place upgrade for the component. If you keep several TouchDesigner projects open, each one carries its own copy of the component and each has to be replaced separately.

Connection errors and what the messages tell you

When the server cannot reach TouchDesigner, the README says you get guided errors rather than raw socket failures. ECONNREFUSED means TouchDesigner is not running, the WebServer DAT from mcp_webserver_base.tox is not started, or the port is wrong; the default is 9981. ETIMEDOUT points at a slow or blocked network path. ENOTFOUND means the host name is invalid, and the guidance is to use 127.0.0.1 unless you deliberately changed it.

Two constraints are worth stating plainly. First, execute_python_script runs arbitrary Python inside TouchDesigner. That is the tool that makes the server powerful and the one that makes it dangerous: an agent with this tool has the same reach as a script you paste into a DAT yourself. Second, get_top_image captures a TOP's current output as an image, which is a read of live state, not a render. Nothing here produces frames on a schedule or works without a running TouchDesigner instance. If your goal is unattended rendering or a CI job, this is the wrong tool.

How it differs from scripting TouchDesigner directly

The obvious alternative is not another MCP server; it is the Python you would otherwise write inside TouchDesigner, or the WebServer DAT endpoints you would call yourself. The difference is in who decides what to call. A hand-written script does one fixed thing. This server hands the agent a menu of fourteen tools and three prompts and lets it choose, then feeds the results back so it can choose again. That loop is the product.

It also explains the cost. A direct script has no version contract to satisfy, because it runs inside the same TouchDesigner build. Here you maintain two artifacts in two languages, the TypeScript server and the Python component, and the compatibility table exists precisely because they can drift apart. If your automation is a fixed sequence of steps, writing it in TouchDesigner's own Python is simpler and has no upgrade surface. If you want an agent to explore a project, inspect errors and adjust parameters interactively, the tool layer earns its keep.

Licence and upkeep

The npm package is MIT licensed, and pyproject.toml declares the same MIT licence for the Python modules, so the server and the component ship under one permissive licence. MIT imposes no conditions on how you use the code beyond keeping the copyright notice; it says nothing about the content you generate with it, and nothing here should be read as legal advice.

The upkeep burden is the compatibility table. The repository's own developer notes describe a version script that keeps the Python API, the expectedApiVersion field, the MCP bundle manifest and registry metadata in sync, and the README tells contributors to run npm run version after editing package.json. If you fork the project and change the tool surface, that script is the thing that keeps your component and your server agreeing with each other. The last push to the repository was on 2026-09-09, and the most recent release listed is v2.0.0 from 2026-07-30.

Editorial conclusion

Adopt it if you already work in TouchDesigner and want an agent to script node creation, parameter edits and Python execution against a live project, and you are willing to keep the .tox component and the npm package in step. Skip it if you need a headless render pipeline or a stable API for production automation: the server talks to a running TouchDesigner instance, and a missing or too-old component stops execution rather than degrading. Before committing, check minApiVersion and expectedApiVersion in package.json against the API version of the component you import, and confirm the WebServer DAT is listening on the port you configured.

Frequently asked questions

Official sources

1. 8beeeaaat/touchdesigner-mcp on GitHub
2. License: MIT
3. Project website
4. README
5. Releases