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. The 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
Requires Docker or Node.js to be installed
1. Clone the repository:
2. Set up the environment file and build:
Copy the template file and adjust the TD_WEB_SERVER_HOST and TD_WEB_SERVER_PORT as needed before building the Docker image.
3. Install the API Server in Your TouchDesigner Project:
Start TouchDesigner and import the td/mcp_webserver_base.tox
component directly under the TouchDesigner project you want to control.
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.
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 like C: e.g. C:\\path\\to\\your\\touchdesigner-mcp\\docker-compose.yml
To use the pre-built JS directly from Node.js:
1. Install the package
2. Install the API Server in Your TouchDesigner Project:
Start TouchDesigner and import the some/node_modules/touchdesigner-mcp-server/td/mcp_webserver_base.tox
component directly under the TouchDesigner project you want to control.
Example: Place it as /project1/mcp_webserver_base
Importing the tox will trigger the some/node_modules/touchdesigner-mcp-server/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.
3. Configure your AI agent:
Example for Claude Desktop
On Windows systems, include the drive letter like C: e.g. C:\\path\\to\\your\\node_modules\\touchdesigner-mcp-server\\dist\\index.js
3. Verify Connection
If the MCP server is recognized, 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 first. When the API server is running properly in TouchDesigner, the agent can use the provided tools to operate TouchDesigner.
MCP Server Features
This server enables operations on TouchDesigner via the Model Context Protocol (MCP) and provides references to various implementation documents.
Tools
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
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. |
Resources
Not implemented
For Developers
Building Client and API Server Code
cp dotenv .env
- Adjust
TD_WEB_SERVER_HOST
andTD_WEB_SERVER_PORT
in the.env
file to match your development environment - Run
make build
ornpm run build
to regenerate the code
When you need to reflect the built code, please restart both the MCP server and TouchDesigner.
Verifying the API Server
npm run test
Run unit tests for the MCP server code and integration tests with TouchDesigner. You can check communication logs by opening the Textport from the TouchDesigner menu.npm run dev
Launch @modelcontextprotocol/inspector to debug various features.
Project Structure Overview
API Code Generation Workflow
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
.
- 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 via 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 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 API client code and Zod schemas for tool validation from the schema YAML 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 -8439PythonMIT License
- -securityAlicense-qualityA Model Context Protocol server that enables AI agents to interact with ClickUp workspaces, allowing task creation, management, and workspace organization through natural language commands.Last updated -313MIT License
- -securityAlicense-qualityA Model Context Protocol server that enables AI assistants to interact with Fingertip's site management capabilities, allowing them to list, view details of, and create websites.Last updated -1TypeScriptMIT License
- -security-license-qualityA Model Context Protocol server implementation that enables AI assistants to interact with Linear project management systems, allowing them to create, retrieve, and modify data related to issues, projects, teams, and users.Last updated -202TypeScript