Skip to main content
Glama
deenesjakoruzh

TouchDesigner MCP

by 8beeeaaat
npmGitHub
TypeScript
MIT License
177
88
  • Linux
  • Apple
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

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.

English / 日本語

Overview

demo clip

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

tutorial

1. Clone the repository:

git clone https://github.com/8beeeaaat/touchdesigner-mcp.git cd touchdesigner-mcp

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.

cp dotenv .env make build

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.

import

You can check boot logs by opening the Textport from the TouchDesigner menu.

import

4. Start the MCP server container

docker-compose up -d

5. Configure your AI agent to use the Docker container:

Example for Claude Desktop

{ "mcpServers": { "touchdesigner": { "command": "docker", "args": [ "compose", "-f", "/path/to/your/touchdesigner-mcp/docker-compose.yml", "exec", "-i", "touchdesigner-mcp-server", "node", "dist/index.js", "--stdio" ] } } }

On Windows systems, include the drive letter like C: e.g.

To use the pre-built JS directly from Node.js:

tutorial

1. Install the package

mkdir some && cd ./some # If you need a new directory npm install touchdesigner-mcp-server

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.

import

You can check boot logs by opening the Textport from the TouchDesigner menu.

import

3. Configure your AI agent:

Example for Claude Desktop

{ "mcpServers": { "touchdesigner": { "args": [ "/path/to/your/node_modules/touchdesigner-mcp-server/dist/index.js", // <-- Replace with the absolute path to node_modules/touchdesigner-mcp-server/dist/index.js "--stdio" ], "command": "node" } } }

On Windows systems, include the drive letter like C: e.g.

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.

demo

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

  1. cp dotenv .env

  2. Adjust TD_WEB_SERVER_HOST and TD_WEB_SERVER_PORT in the .env file to match your development environment

  3. Run make build or npm 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

├── src/ # MCP server source code │ ├── api/ # OpenAPI spec for TD WebServer │ ├── core/ # Core utilities (logger, error handling) │ ├── features/ # MCP feature implementations │ │ ├── prompts/ # Prompt handlers │ │ ├── resources/ # Resource handlers │ │ └── tools/ # Tool handlers (e.g., tdTools.ts) │ ├── gen/ # Code generated from OpenAPI schema for MCP server │ ├── server/ # MCP server logic (connections, main server class) │ ├── tdClient/ # TD connection API client │ ├── index.ts # Main entry point for Node.js server │ └── ... ├── td/ # TouchDesigner related files │ ├── modules/ # Python modules for TouchDesigner │ │ ├── mcp/ # Core logic for handling MCP requests in TD │ │ │ ├── controllers/ # API request controllers (api_controller.py, generated_handlers.py) │ │ │ └── services/ # Business logic (api_service.py) │ │ ├── td_server/ # Python model code generated from OpenAPI schema │ │ └── utils/ # Shared Python utilities │ ├── templates/ # Mustache templates for Python code generation │ ├── genHandlers.js # Node.js script for generating generated_handlers.py │ ├── import_modules.py # Helper script to import API server modules into TD │ └── mcp_webserver_base.tox # Main TouchDesigner component ├── tests/ # Test code │ ├── integration/ │ └── unit/ ├── .env # Local environment variables (git ignored) ├── dotenv # Template for .env └── orval.config.ts # Orval config (TS client generation)

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.

  1. Python server generation (

    • 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.

  2. Python handler generation (

    • 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 in td/modules/mcp/services/api_service.py.

  3. TypeScript client generation (

    • Uses Orval to generate API client code and Zod schemas for tool validation from the schema YAML bundled by openapi-generator-cli.

    • Generates a typed TypeScript client (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).

Contributing

We welcome your contributions!

  1. Fork the repository

  2. Create a feature branch (git checkout -b feature/amazing-feature)

  3. Make your changes

  4. Add tests and ensure everything works (npm test)

  5. Commit your changes (git commit -m 'Add some amazing feature')

  6. Push to your branch (git push origin feature/amazing-feature)

  7. Open a pull request

Please always include appropriate tests when making implementation changes.

License

MIT

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

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.

  1. Overview
    1. Usage
      1. 1. Clone the repository:
      2. 2. Set up the environment file and build:
      3. 3. Install the API Server in Your TouchDesigner Project:
      4. 4. Start the MCP server container
      5. 5. Configure your AI agent to use the Docker container:
      6. 1. Install the package
      7. 2. Install the API Server in Your TouchDesigner Project:
      8. 3. Configure your AI agent:
      9. 3. Verify Connection
    2. MCP Server Features
      1. Tools
      2. Prompts
      3. Resources
    3. For Developers
      1. Building Client and API Server Code
      2. Verifying the API Server
      3. Project Structure Overview
      4. API Code Generation Workflow
    4. Contributing
      1. License

        Related MCP Servers

        • Appwrite MCP Serverofficial

          appwrite
          A
          security
          A
          license
          A
          quality
          A 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 -
          54
          MIT License
          • Linux
          • Apple

        • SupaUI MCP Server

          buoooou
          A
          security
          F
          license
          A
          quality
          A Model Context Protocol server that enables AI agents to generate, fetch, and manage UI components through natural language interactions.
          Last updated -
          3
          36
          6

        • MCP Android Agent

          nim444
          -
          security
          A
          license
          -
          quality
          A 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 -
          27
          MIT License
          • Apple

        • Agentic Tools MCP Server

          Pimzino
          A
          security
          A
          license
          A
          quality
          A Model Context Protocol server providing AI assistants with comprehensive project, task, and subtask management capabilities with project-specific storage.
          Last updated -
          29
          54
          62
          MIT License
          • Apple
          • Linux

        View all related MCP servers

        New MCP Servers

        MCP directory API

        We provide all the information about MCP servers via our MCP API.

        curl -X GET 'https://glama.ai/api/mcp/v1/servers/8beeeaaat/touchdesigner-mcp'

        If you have feedback or need assistance with the MCP directory API, please join our Discord server