TouchDesigner MCP connects AI agents to TouchDesigner through the Model Context Protocol and TouchDesigner's WebServer DAT. The 8beeeaaat/touchdesigner-mcp repository describes it as an MCP server that can create, modify, and delete nodes, query project structure, control TouchDesigner through Python scripts, and capture a TOP output as an image. During the GitHub check on August 26, 2026, the repository was MIT licensed, had 505 stars and 51 forks, and the latest release was v2.0.0, published on July 30, 2026.
For Educasium, this connector is relevant for visual installations, interactive scenography, real-time media, and creative prototypes. It speaks to a tool where node graphs, parameters, and visual feedback matter more than a static page. The framing still needs precision: installation has both a Node.js MCP server and a TouchDesigner component, npm and API versions move on two different axes, and the tool exposes execute_python_script.
Contents
- What TouchDesigner MCP does
- Installation and architecture
- Exposed tools
- Versioning and compatibility
- Comparison with Blender, Houdini, and Unity
- Security and limits
- Educasium position
What TouchDesigner MCP does
Key point: TouchDesigner MCP bridges an AI agent and an open TouchDesigner project, with actions on nodes, parameters, scripts, and TOP images. It is built for a real-time visual environment, not for generating a website or final render out of context.
A bridge to WebServer DAT
The README explains that TouchDesigner MCP acts as a bridge between AI models and the WebServer DAT. That point is central: the agent does not magically control TouchDesigner; it sends requests to a server layer exposed inside the project. The TouchDesigner project must contain the mcp_webserver_base.tox component, ideally placed under project1/mcp_webserver_base according to the installation guide.
The MCP server can then request operations on nodes, parameters, and project structure. For creative workflows, this opens simple uses: create a network base, modify parameters, read errors, capture a TOP, and iterate. For professional work, the same loop must remain observable because a real-time installation also depends on hardware, inputs, performance, and scenography.
Why it differs from a classic 3D MCP
TouchDesigner is not only modeling software. It is often used for real-time visual systems, interaction, video feeds, sensors, performances, and installations. An MCP connector therefore has a specific value here: helping manipulate a live network, with changing parameters and output images to verify.
The get_top_image command matters in that logic. It captures the current output of a TOP as an image. That gives the model visual feedback on the produced result, even though artistic and technical judgment remains human. For Educasium, this create, capture, correct loop is more educational than a raw command list.
Installation and architecture
Key point: installation requires a TouchDesigner component inside the project and an MCP server launched through the Claude Desktop bundle, npm, or Docker. If either side is missing, the connection breaks.
TouchDesigner-side setup
The installation guide first asks users to download touchdesigner-mcp-td.zip from the latest release, extract it, then import mcp_webserver_base.tox into the TouchDesigner project. It recommends the project1/mcp_webserver_base path. It also stresses a practical point: do not change the folder structure, because the component references modules through relative paths.
The latest verified release contained two assets: touchdesigner-mcp-td.zip and touchdesigner-mcp.mcpb. The first belongs to the TouchDesigner side. The second is the MCP bundle for Claude Desktop. For a course, prepare both files and test the Textport before the session.
Node.js MCP server
The verified npm package is named touchdesigner-mcp-server, version 2.0.0, type module, with a touchdesigner-mcp-server binary pointing to dist/cli.js. The guide says npm installations for Claude Code, Codex, and other clients use npx -y touchdesigner-mcp-server@latest --stdio. It specifies Node.js 20.x or later for npm-based installs.
The official architecture describes two processes: a Node.js MCP server and a Python WebServer inside TouchDesigner. The Node.js server can run in stdio mode for a local one-to-one connection, or in Streamable HTTP mode for HTTP/SSE use. It then communicates with TouchDesigner through the HTTP API exposed by the WebServer DAT, defaulting to http://127.0.0.1:9981.
Exposed tools
Key point: tools cover node creation, deletion, parameters, Python introspection, errors, script execution, and TOP capture. That coverage fits real-time demos and TouchDesigner graph workshops.
Nodes and parameters
The README table lists create_td_node for node creation, delete_td_node for deletion, get_td_nodes for listing nodes under a parent with optional filtering, get_td_node_parameters for reading parameters, and update_td_node_parameters for changing them. It also lists get_td_node_errors for checking errors on a node and its children.
These commands support a clear teaching progression. A learner can ask for a small network, read available parameters, change a setting, then query errors. In TouchDesigner, that loop matters because a path, node type, or parameter error can leave part of the network inactive without producing an obvious signal for beginners.
Python, classes, and TOP image
The README lists execute_python_script for arbitrary Python script execution in TouchDesigner, exec_node_method for calling a Python method on a node, get_td_classes for listing TouchDesigner Python classes, get_td_class_details for details of a class or module, and get_td_module_help for Python help. These tools make the connector a scripting assistant, not only a parameter editor.
get_top_image captures the current output of a TOP node as an image. For visual installations, this is what makes iteration more concrete: the assistant can see an output, comment on the result, then propose a correction. This capability does not replace checking the real display, projector, LED wall, or interactive device, but it gives a first control loop.
Versioning and compatibility
Key point: TouchDesigner MCP separates the npm package version from the TouchDesigner component API version. This is the most important operational trap during updates.
Two version axes
The README explains that the MCP server and TouchDesigner component are versioned on two independent axes: the npm package version and the API version, which is the contract between the MCP server and the .tox component. Each release declares expectedApiVersion and minApiVersion. The minimum shown in the verified README is 1.3.0.
This rule prevents a common mistake: assuming an npm package update is enough. The README says the npm package version itself never gates compatibility. What matters is compatibility between the API expected by the server and the API exposed by the TouchDesigner component.
Behavior when versions differ
The troubleshooting table says a component at the expected API version works silently. An older component above the minimum triggers an update recommended warning and continues. A newer component within the same major also triggers a warning. A major above expected, or a version below the minimum, stops execution.
The guide also gives the fix: download the latest touchdesigner-mcp-td.zip, replace the existing folder, remove the old mcp_webserver_base component from the project, import the new .tox, then restart TouchDesigner and the AI agent. For Educasium, this belongs in the course material because it avoids many false diagnoses.
Comparison with Blender, Houdini, and Unity
Key point: TouchDesigner MCP is the best fit in this list when the subject is a real-time visual installation or interactive network. It does not play the same role as a modeling MCP or game-engine MCP.
| Option | Natural use | Main strength | Limit to watch |
|---|---|---|---|
| TouchDesigner MCP | Visual installations, real time, TOPs, interactive networks | Parameters, errors, scripts, and TOP capture | .tox component API version must be maintained |
| Blender MCP | 3D initiation, assets, accessible scenes | Free software and broad community | Less oriented toward live performance and sensors |
| Houdini MCP | Procedural graphs, wrangles, VFX | Node-based networks and procedural geometry | More technical, centered on Houdini |
| Unity MCP | Interactive scenes, games, real-time walkthroughs | Runtime engine and game assets | Heavier workflow than a TouchDesigner patch |
Choose by expected output
If the goal is an image, a 3D scene, or an asset library, TouchDesigner is not necessarily the simplest entry point. If the goal is a real-time experience reacting to parameters, a video feed, or interaction, TouchDesigner MCP becomes much more natural.
That distinction helps Educasium segment courses. A Blender module teaches the 3D scene. A Houdini module teaches advanced procedural work. A TouchDesigner module teaches live iteration: network, parameters, TOP output, errors, performance, and human control.
Security and limits
Key point: execute_python_script should be treated as a real execution surface inside TouchDesigner. Automation gains do not justify letting the agent act without controls in a client project or active installation.
Arbitrary scripts
The README names execute_python_script as arbitrary Python script execution in TouchDesigner. It is useful for inspection, automation, or corrections that structured tools do not cover. It is also the point that requires rules: work on copies, review the script, limit file access, and do not test directly on a critical show file.
exec_node_method requires the same caution. Calling a Python method on a node can be legitimate, but it depends on the node, context, and side effects. In training, start with structured read, parameter, and error tools before moving to scripts.
Connection and transport
Stdio mode is local and one-to-one, while Streamable HTTP mode can be network accessible depending on configuration. The installation guide also describes Docker and variables such as MCP_HTTP_PORT or TD_HOST for HTTP cases. That can be useful in development, but it is not the simplest choice for an introduction.
Connection errors are documented with concrete causes: TouchDesigner not running, WebServer DAT missing or stopped, incorrect default port 9981, timeout, or invalid host name. The client also caches failed connection checks for 60 seconds to avoid spamming TouchDesigner. That detail matters when diagnosing a demo that has just been fixed but still returns an old error.
Educasium position
Key point: Educasium can present TouchDesigner MCP as a strong case study for AI applied to real-time visual environments, with heavy emphasis on versioning, security, and visual verification. The positioning remains experimental unless production validation is documented.
Proposed training
A reasonable workshop starts with installation: import mcp_webserver_base.tox, keep the folder structure, verify the Textport, install the Claude Desktop bundle or configure npx for Codex, then run a first get_td_info call. Only then should it move to a small network: create a node, read parameters, change a value, check errors, and capture a TOP.
That progression teaches a reliable method. The learner understands that the assistant needs an active component, a correct port, a compatible API, and visual validation. They also learn to distinguish a prompt problem from a connection or version problem.
Logical next step
The logical next step would be an Educasium grid for testing real-time MCPs: installation, port, transport, API version, read tools, write tools, arbitrary scripts, image capture, performance, and rollback. TouchDesigner MCP is a good candidate for that grid because it already documents many of those points.