touchdesigner-mcp: driving TouchDesigner from an MCP client
MCP server for TouchDesigner
At a glance
- What is it?
- An MCP server that exposes TouchDesigner node operations, parameter reads and writes, Python execution and TOP image capture as agent tools. The interesting part is not the tool list but the two-axis version contract between the npm package and the .tox component.
- Who is it for?
- Adopt it if you already run TouchDesigner interactively and want an agent to build or inspect node networks through the WebServer DAT, and you are willing to keep the .tox component and the npm package in step. Do not adopt it if you need headless rendering or a stable API surface for unattended pipelines, since the compatibility table stops execution on a MAJOR mismatch and the Resources surface is not implemented.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 7 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap touchdesigner-mcp fills: agents that cannot touch a node graph
TouchDesigner projects are graphs of operators built in a visual editor. An AI agent with no bridge into that editor can write Python for you, but it cannot create the node, wire the connection, set the parameter and check whether the result errors out. This server exists to close that loop. The README states the goal directly: it is an implementation of an MCP server for TouchDesigner whose purpose is to let AI agents control and operate TouchDesigner projects.
The audience is narrow and specific. You need TouchDesigner running on the same machine or reachable over the network, a WebServer DAT loaded from the project's .tox component, and an MCP-capable client such as Claude Desktop (the README names it in the compatibility recovery steps). If you do not already work inside TouchDesigner, nothing here applies to you. If you do, the value is that node creation, parameter updates and error checks become agent-callable operations instead of manual clicks.
What the agent can actually call: fourteen tools, three prompts, no resources
The tool surface is enumerated in the README table and splits into three rough groups. Structural operations: create_td_node, delete_td_node, update_td_node_parameters, exec_node_method. Inspection: get_td_nodes, get_td_node_parameters, get_td_node_errors, get_td_info. Introspection of the TouchDesigner Python environment itself: get_td_classes, get_td_class_details, get_td_module_help, describe_td_tools. Two entries sit outside those groups. execute_python_script runs an arbitrary Python script inside TouchDesigner, and get_top_image captures the current output of a TOP node as an image.
That last one is the most consequential tool in the list. It means the agent can look at rendered output rather than only reading parameter values, which is the difference between editing a graph blind and editing it against a visual result.
The prompts are narrower: fuzzy node search by name, family or type, instructions for connecting nodes, and a recursive error check. The README is blunt about the third primitive type: Resources are listed as not implemented. If your client or workflow depends on MCP resources rather than tools and prompts, that part of the protocol is simply absent here. Note also that execute_python_script and exec_node_method are effectively arbitrary code execution inside your TouchDesigner process. The README does not describe a sandbox, and you should not assume one.
Architecture: a bridge to the WebServer DAT, not a plugin
The mechanism is a bridge. The server sits between an AI model and the TouchDesigner WebServer DAT, and the README describes the flow as enabling agents to create, modify and delete nodes, query node properties and project structure, and control TouchDesigner programmatically via Python scripts. The TypeScript side speaks MCP to the client and HTTP to the WebServer DAT. The Python side lives in the TouchDesigner project as a component imported from mcp_webserver_base.tox.
That split explains most of the operational behaviour. The default port is 9981, and connection errors are surfaced with concrete causes: ECONNREFUSED when TouchDesigner is not running or the WebServer DAT is not started, ETIMEDOUT when TouchDesigner responds slowly or the network blocks the call, ENOTFOUND when the host name is wrong. The README recommends 127.0.0.1 unless you deliberately changed it.
One design detail worth calling out because it affects how failures feel in practice: TouchDesignerClient caches failed connection checks for 60 seconds. Subsequent tool calls reuse the cached error rather than retrying immediately, and the retry happens automatically after the TTL expires. That protects TouchDesigner from a burst of retries, but it also means that if you start the WebServer DAT right after a failed call, the next several calls may still report the old error until the cache expires.
Getting it running: the .tox, the port, and the npm package
The README defers setup to docs/installation.md and to the Developer Guide at docs/development.md for local setup, client configuration, project structure and release workflow. What it does spell out is the recovery path for a compatibility failure, and that path is also the closest thing to an install sequence in the supplied material: download touchdesigner-mcp-td.zip from the latest release, delete the existing touchdesigner-mcp-td folder and replace it with the extracted contents, remove the old mcp_webserver_base component from the TouchDesigner project and import the .tox from the new folder, then restart TouchDesigner and the MCP client.
The npm package is touchdesigner-mcp-server, and the README points updaters at the Latest Release page for the procedure. For people working on the server itself, the README gives one maintenance command: run npm run version after editing package.json, or use npm version, which keeps the Python API (pyproject.toml plus td/modules/utils/version.py), mcpCompatibility.expectedApiVersion, the MCP bundle manifest and the registry metadata in sync so the runtime compatibility check succeeds.
The config key that matters operationally is the port, default 9981, alongside the host, which the README suggests leaving at 127.0.0.1. If the MCP server process runs somewhere other than the TouchDesigner machine, that default will not work and the host has to be changed deliberately.
The two-axis version contract is the real design decision here
Most MCP servers have one version number. This one has two, and the README is explicit that the npm package version and the API version (the contract between the MCP server and the .tox component) move independently. Each release declares the API version it ships with, expectedApiVersion, and the minimum it supports, minApiVersion, currently 1.3.0. The connected component's API version is compared against those two values, and the npm package version itself never gates compatibility. The practical consequence is stated plainly: updating the MCP server alone never invalidates a supported component.
The failure table has five rows and two of them stop execution. A component matching the expected API version works silently. A component at or above the minimum but below the expected version gets an "Update Recommended" notice appended to responses and continues. A component above the expected version within the same MAJOR gets a warning to update the MCP server and continues. A component a MAJOR above expected stops execution and requires updating the MCP server. A component below the minimum, or one whose version is missing, stops execution and requires updating the component.
This is a stricter posture than most integrations take, and it is defensible: a MAJOR bump in a contract that executes Python inside a running creative application is not something to paper over with a warning. The cost is that a mismatch is a hard stop in the middle of a session, and the fix requires a manual .tox swap plus a restart of both TouchDesigner and the agent. The README also notes that the structured error text is logged through ILog, so a failed call leaves a trace rather than vanishing.
Where it is the wrong tool, and what to use instead
Three limits are visible in the material. Resources are not implemented, so clients that lean on that primitive get nothing. The server is a bridge to a running TouchDesigner instance, which means an interactive session with the WebServer DAT active; the README's own troubleshooting assumes you can start TouchDesigner and check the DAT. And execute_python_script runs arbitrary code in that process with no documented sandbox, which is a poor fit for any environment where the agent's output is not reviewed.
The alternative worth naming is TouchDesigner's own Python environment. Every tool in this server's list maps to something you can do by writing Python against the TouchDesigner API directly: create operators, set parameters, walk the node tree, call methods on nodes. The difference is the interface and the loop. Hand-written Python is a file you run and debug, with no agent in the middle and no protocol layer. This server trades that directness for a conversational loop where the model proposes a node or a parameter change, the server applies it through the WebServer DAT, and the result comes back as a tool response, including a captured TOP image. If you want a scripted, repeatable build, plain Python is simpler and has no version contract to satisfy. If you want an agent iterating on a graph with visual feedback, the MCP layer is the point.
A second comparison is worth stating because it is easy to conflate: this is not a headless rendering or batch pipeline tool. Nothing in the supplied material suggests it can drive TouchDesigner without a running instance and the WebServer DAT.
Maintenance cost and the MIT licence
The maintenance burden has two halves and they are not equal. The npm side updates like any package. The TouchDesigner side is a folder of files and a .tox component that has to be replaced by hand: delete touchdesigner-mcp-td, extract the new zip, remove the old mcp_webserver_base component from the project and import the new .tox, then restart both TouchDesigner and the agent. That is a manual operation on a creative project, and it is the step most likely to be skipped until a compatibility error forces it.
The version-sync command, npm run version, exists precisely because four artefacts have to agree: the Python API in pyproject.toml and td/modules/utils/version.py, mcpCompatibility.expectedApiVersion, the MCP bundle manifest and the registry metadata. For contributors, forgetting it means the runtime check fails. For users, it means the release you download should already be internally consistent, and the failure mode you are more likely to hit is your component drifting behind the server.
The project is MIT licensed. That is permissive and unsurprising for an MCP server, but the licence covers the code in this repository. The supplied material does not describe the licence terms attached to the TouchDesigner .tox component or to TouchDesigner itself, and those are separate matters. Nothing here is legal advice; check the terms that apply to your TouchDesigner installation before shipping anything built on this.
Editorial conclusion
Adopt it if you already run TouchDesigner interactively and want an agent to build or inspect node networks through the WebServer DAT, and you are willing to keep the .tox component and the npm package in step. Do not adopt it if you need headless rendering or a stable API surface for unattended pipelines, since the compatibility table stops execution on a MAJOR mismatch and the Resources surface is not implemented. Before wiring it into a client, confirm your component's API version against expectedApiVersion and minApiVersion (1.3.0), and verify that port 9981 is reachable from wherever the MCP server process runs.
Community notes