Required for code generation during development, used to generate API client/server schemas for the TouchDesigner integration.
Required runtime environment for the TouchDesigner MCP server, enabling the bridge between AI models and TouchDesigner.
Used within TouchDesigner for scripting and controlling nodes, allowing AI agents to execute Python code to manipulate TouchDesigner projects.
This is an implementation of an MCP (Model Context Protocol) server for TouchDesigner. The goal is to enable AI agents to control and operate TouchDesigner projects.
TouchDesigner MCP acts as a bridge between AI models and the TouchDesigner WebServer DAT, enabling AI agents to:
Requires Node.js to be installed
mkdir some && cd ./some (If you need)
npm install touchdesigner-mcp-server
Start TouchDesigner and import the td/mcp_webserver_base.tox component directly under your TouchDesigner project.
Example: Place it as /project1/mcp_webserver_base
Importing the tox will trigger the td/import_modules.py script, which loads modules such as API server controllers.
You can check boot logs by opening the Textport from the TouchDesigner menu.
With TouchDesigner running, configure your AI agent (Claude Desktop, Cursor, VSCode CopilotChat, etc.) to connect to the MCP server.
Example: Claude Desktop
On Windows system, please include the drive letter such as C: e.g. C:\\path\\to\\your\\node_modules\\touchdesigner-mcp-server\\dist\\index.js
If the MCP server is recognized, setup is complete. Restart the agent, if not recognized. If you see an error at startup, try launching the agent again after starting TouchDesigner. If the API server is running in TouchDesigner, the agent can use TouchDesigner via the provided tools.
This server enables operations on TouchDesigner via the Model Context Protocol (MCP) and provides references to various implementation documents.
Tools allow AI agents to perform actions in TouchDesigner.
| Tool Name | Description |
|---|---|
create_td_node | Create a new node. |
delete_td_node | Delete an existing node. |
exec_node_method | Call a Python method on a node. |
execute_python_script | Execute an arbitrary Python script in TD. |
get_td_class_details | Get details of a TD Python class/module. |
get_td_classes | Get a list of TouchDesigner Python classes. |
get_td_info | Get information about the TD server environment. |
get_td_node_parameters | Get parameters of a specific node. |
get_td_nodes | Get nodes under a parent path (optionally filtered). |
update_td_node_parameters | Update parameters of a specific node. |
Prompts provide instructions for AI agents to perform specific actions in TouchDesigner.
| Prompt Name | Description |
|---|---|
Search node | Fuzzy search for nodes and retrieve information based on name, family, type. |
Node connection | Provide instructions to connect nodes within TouchDesigner. |
Check node errors | Check errors for a specified node, recursively for child nodes if any. |
Not implemented
Run npm run build to generate the following code:
Start TouchDesigner and import the td/mcp_webserver_base.tox component directly under your project.
Importing the tox will trigger the td/import_modules.py script, which loads modules such as API server controllers.
Ensure that the Python modules in the td/modules directory are accessible from the mcp_webserver_base component.
Run npm run test to execute unit and integration tests for the MCP server code and TouchDesigner connection.
You can check communication logs by opening the Textport from the TouchDesigner menu.
You can debug with @modelcontextprotocol/inspector using npm run dev.
TIPS
mcp_webserver_base.tox includes a WebServer DAT configured to link the MCP server and TouchDesigner.
Ensure this DAT is active and running on the port specified by TD_WEB_SERVER_URL in your .env file (default: 9981).
To change the port:
TD_WEB_SERVER_PORT in .envnpm run buildWith TouchDesigner running, configure your AI agent (Cursor, Claude Desktop, VSCode CopilotChat, etc.) to connect to the MCP server.
On Windows system, please include the drive letter such as C: e.g. C:\\path\\to\\your\\touchdesigner-mcp\\dist\\index.js
This project uses OpenAPI-based code generation tools (Orval / openapi-generator-cli):
API Definition: The API contract between the Node.js MCP server and the Python server running inside TouchDesigner is defined in src/api/index.yml.
npm run gen:webserver):openapi-generator-cli via Docker.src/api/index.yml.td/modules/td_server/) based on the API definition. This code runs inside TouchDesigner via WebServer DAT.npm run gen:handlers):td/genHandlers.js) and Mustache templates (td/templates/).td/modules/mcp/controllers/generated_handlers.py) that connect to business logic in td/modules/mcp/services/api_service.py.npm run gen:mcp):Orval to generate API client code and Zod schemas for tool validation from the schema YAML bundled by openapi-generator-cli.src/tdClient/) used by the Node.js server to make requests to the WebServer DAT.The build process (npm run build) runs all necessary generation steps (npm run gen), followed by TypeScript compilation (tsc).
We welcome your contributions!
git checkout -b feature/amazing-feature)npm test)git commit -m 'Add some amazing feature')git push origin feature/amazing-feature)Please always include appropriate tests when making implementation changes.
MIT
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
A Model Context Protocol server that enables AI agents to control and operate TouchDesigner projects through creation, modification, and querying of nodes and project structures.