touchdesigner

This MCP server implements TouchDesigner control via the MCP (Model Context Protocol), enabling AI agents to create, modify, query, and manage TouchDesigner projects through a unified API. It exposes a set of tools that let agents construct and manipulate nodes, run Python scripts inside TouchDesigner, and inspect node parameters and class details. Use the provided tools to craft workflows that programmatically build or adjust your TouchDesigner projects, or to validate the project structure before running complex automations. The server also includes prompts to guide agents on how to search for nodes, connect nodes, and check for node errors, making it easier to assemble robust TouchDesigner pipelines.

Prerequisites:

• Node.js (v14+ recommended) and npm
• Access to a working TouchDesigner WebServer DAT if you plan to test against a local TouchDesigner instance

Installation steps:

1. Install the MCP server package from npm

   • Using npm (local project): npm install touchdesigner-mcp-server
   • Or globally (for quick access via npx): npm install -g touchdesigner-mcp-server

2. Verify installation

   • Run: npm list -g --depth=0 | grep touchdesigner-mcp-server (or check package.json in your project)

3. Prepare your MCP configuration (example):

   • The MCP config uses the npx invocation as the launcher. See the mcp_config section for a ready-to-use template.

4. Start using the server

   • If using npx as shown in mcp_config, the server will be launched by your MCP runner with the provided command and arguments.

Note: If you’re updating from a previous release, follow the project’s release notes and replace the touchedtd mcp assets as described in the docs.

Tips and common issues:

• Ensure the TouchDesigner WebServer DAT is running and accessible (default port 9981) when using the tools that interact with TouchDesigner.
• If you encounter connection errors, verify your network path to 127.0.0.1 or your configured host, and restart both TouchDesigner and the MCP server as needed.
• Compatibility checks follow semantic versioning. If you see compatibility warnings or errors, review the compatibility matrix in the Troubleshooting section and update to compatible versions as described in the project docs.
• The server provides helper prompts such as Search node, Node connection, and Check node errors to guide AI agents in performing common tasks within TouchDesigner.
• When developing locally, keep the Python API and MCP bundle manifest in sync by following the developer guidance documented in the repository.