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.
Used to develop the MCP server code with type safety, providing a robust interface between AI agents and TouchDesigner.
Used for schema validation in the TypeScript implementation, ensuring proper data validation for tool inputs.
TouchDesigner MCP
This is an implementation of an MCP (Model Context Protocol) server for TouchDesigner. Its goal is to enable AI agents to control and operate TouchDesigner projects.
Overview
TouchDesigner MCP acts as a bridge between AI models and the TouchDesigner WebServer DAT, enabling AI agents to:
- Create, modify, and delete nodes
- Query node properties and project structure
- Programmatically control TouchDesigner via Python scripts
Usage
1. Download Files
Download the following from the releases page:
- TouchDesigner Components:
touchdesigner-mcp-td.zip
- Desktop Extension (.dxt):
touchdesigner-mcp.dxt
2. Set up TouchDesigner Components
- Extract the TouchDesigner components from
touchdesigner-mcp-td.zip
. - Import
mcp_webserver_base.tox
into your TouchDesigner project. - Place it at
/project1/mcp_webserver_base
.
https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4
You can check the startup logs by opening the Textport from the TouchDesigner menu.
3. Install the Desktop Extension
Double-click the touchdesigner-mcp.dxt
file to install the extension in Claude Desktop.
https://github.com/user-attachments/assets/0786d244-8b82-4387-bbe4-9da048212854
4. Connect to the Server
The extension will automatically handle the connection to the TouchDesigner server.
⚠️ Important: The directory structure must be preserved exactly as extracted. The mcp_webserver_base.tox
component references relative paths to the modules/
directory and other files.
Requires Node.js to be installed.
1. Set up TouchDesigner Components
- Download and extract the TouchDesigner components from
touchdesigner-mcp-td.zip
(releases page). - Import
mcp_webserver_base.tox
into your TouchDesigner project. - Place it at
/project1/mcp_webserver_base
.
https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4
You can check the startup logs by opening the Textport from the TouchDesigner menu.
2. Set up the MCP Server Configuration
Example for Claude Desktop:
Customization: You can customize the TouchDesigner server connection by adding --host
and --port
arguments:
1. Clone the repository
2. Build the Docker image
3. Install the API Server in Your TouchDesigner Project
Start TouchDesigner and import the td/mcp_webserver_base.tox
component into the project you want to control.
Example: Place it at /project1/mcp_webserver_base
.
Importing the .tox
file will trigger the td/import_modules.py
script, which loads the necessary modules for the API server.
https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4
You can check the startup logs by opening the Textport from the TouchDesigner menu.
4. Start the MCP server container
5. Configure your AI agent to use the Docker container
Example for Claude Desktop:
On Windows systems, include the drive letter, e.g., C:\path\to\your\touchdesigner-mcp\docker-compose.yml
.
Note: You can customize the TouchDesigner server connection by adding --host
and --port
arguments:
Verify Connection
If the MCP server is recognized, the setup is complete. If it's not recognized, try restarting your AI agent. If you see an error at startup, try launching the agent again after starting TouchDesigner. When the API server is running properly in TouchDesigner, the agent can use the provided tools to operate it.
Directory Structure Requirements
Critical: When using any method, you must maintain the original directory structure:
The mcp_webserver_base.tox
component uses relative paths to locate Python modules. Moving or reorganizing these files will cause import errors in TouchDesigner.
MCP Server Features
This server enables AI agents to perform operations in TouchDesigner using the Model Context Protocol (MCP).
Tools
Tools allow AI agents to perform actions in TouchDesigner.
Tool Name | Description |
---|---|
create_td_node | Creates a new node. |
delete_td_node | Deletes an existing node. |
exec_node_method | Calls a Python method on a node. |
execute_python_script | Executes an arbitrary Python script in TouchDesigner. |
get_td_class_details | Gets details of a TouchDesigner Python class or module. |
get_td_classes | Gets a list of TouchDesigner Python classes. |
get_td_info | Gets information about the TouchDesigner server environment. |
get_td_node_parameters | Gets the parameters of a specific node. |
get_td_nodes | Gets nodes under a parent path, with optional filtering. |
update_td_node_parameters | Updates the parameters of a specific node. |
Prompts
Prompts provide instructions for AI agents to perform specific actions in TouchDesigner.
Prompt Name | Description |
---|---|
Search node | Fuzzy searches for nodes and retrieves information based on name, family, or type. |
Node connection | Provides instructions to connect nodes within TouchDesigner. |
Check node errors | Checks for errors on a specified node, and recursively for its children. |
Resources
Not implemented.
For Developers
Quick Start for Development
- Set up your environment:
- Build the project:
- Available commands:
Note: When you update the code, you must restart both the MCP server and TouchDesigner to apply the changes.
Project Structure Overview
API Code Generation Workflow
This project uses OpenAPI-based code generation tools (Orval and 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
.
- Python server generation (
npm run gen:webserver
):- Uses
openapi-generator-cli
via Docker. - Reads
src/api/index.yml
. - Generates a Python server skeleton (
td/modules/td_server/
) based on the API definition. This code runs inside TouchDesigner's WebServer DAT. - Requires Docker to be installed and running.
- Uses
- Python handler generation (
npm run gen:handlers
):- Uses a custom Node.js script (
td/genHandlers.js
) and Mustache templates (td/templates/
). - Reads the generated Python server code or OpenAPI spec.
- Generates handler implementations (
td/modules/mcp/controllers/generated_handlers.py
) that connect to the business logic intd/modules/mcp/services/api_service.py
.
- Uses a custom Node.js script (
- TypeScript client generation (
npm run gen:mcp
):- Uses
Orval
to generate an API client and Zod schemas for tool validation from the schema YAML, which is bundled byopenapi-generator-cli
. - Generates a typed TypeScript client (
src/tdClient/
) used by the Node.js server to make requests to the WebServer DAT.
- Uses
The build process (npm run build
) runs all necessary generation steps (npm run gen
), followed by TypeScript compilation (tsc
).
Contributing
We welcome your contributions!
- Fork the repository.
- Create a feature branch (
git checkout -b feature/amazing-feature
). - Make your changes.
- Add tests and ensure everything works (
npm test
). - Commit your changes (
git commit -m 'Add some amazing feature'
). - Push to your branch (
git push origin feature/amazing-feature
). - Open a pull request.
Please always include appropriate tests when making implementation changes.
License
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.
Related MCP Servers
- AsecurityAlicenseAqualityA Model Context Protocol server that allows AI assistants to interact with Appwrite's API, providing tools to manage databases, users, functions, teams, and other resources within Appwrite projects.Last updated -8450PythonMIT License
- AsecurityFlicenseAqualityA Model Context Protocol server that enables AI agents to generate, fetch, and manage UI components through natural language interactions.Last updated -36194TypeScript
- -securityAlicense-qualityA Model Context Protocol server that enables AI agents to control and automate Android devices through natural language, supporting actions like app management, UI interactions, and device monitoring.Last updated -17PythonMIT License
- AsecurityAlicenseAqualityA Model Context Protocol server providing AI assistants with comprehensive project, task, and subtask management capabilities with project-specific storage.Last updated -294552TypeScriptMIT License