TouchDesigner MCP server for AI agents

TouchDesigner MCP is an implementation of the Model Context Protocol server that enables AI agents to control and operate TouchDesigner projects. It serves as a bridge between AI models and TouchDesigner, allowing them to create and modify nodes, query properties, and run Python scripts programmatically.

Installation Options

Method 1: Using Claude Desktop and Desktop Extensions (Recommended)

Download Required Files

From the releases page, download:
- TouchDesigner Components (touchdesigner-mcp-td.zip)
- Desktop Extension (touchdesigner-mcp.dxt)

Set Up TouchDesigner Components

Extract the TouchDesigner components from the ZIP file
Import mcp_webserver_base.tox into your TouchDesigner project
Place it at /project1/mcp_webserver_base

You can verify successful setup by opening the Textport from the TouchDesigner menu to check startup logs.

Install the Desktop Extension

Double-click the touchdesigner-mcp.dxt file to install it in Claude Desktop. The extension will automatically handle the connection to the TouchDesigner server.

⚠️ Important: Maintain the directory structure exactly as extracted. The mcp_webserver_base.tox component uses relative paths to locate modules.

Method 2: Using npx

Set Up TouchDesigner Components

Download and 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

Set Up MCP Server Configuration

Example for Claude Desktop:

{
  "mcpServers": {
    "touchdesigner": {
      "command": "npx",
      "args": ["-y", "touchdesigner-mcp-server@latest", "--stdio"]
    }
  }
}

Customization: You can customize the server connection:

"args": [
  "-y",
  "touchdesigner-mcp-server@latest",
  "--stdio",
  "--host=http://custom_host",
  "--port=9982"
]

Method 3: Using Docker

Set Up Docker Environment

Clone the repository:

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

Build the Docker image:
```
make build
```

Install in TouchDesigner

Start TouchDesigner and import the td/mcp_webserver_base.tox component
Place it at /project1/mcp_webserver_base

Start and Configure the MCP Server

Start the Docker container:
```
docker-compose up -d
```

Configure your AI agent (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/cli.js",
        "--stdio",
        "--host=http://host.docker.internal"
      ]
    }
  }
}

Verifying Connection

If the MCP server is recognized, the setup is complete. If issues occur:

Try restarting your AI agent
Launch the agent again after starting TouchDesigner
Ensure TouchDesigner's API server is properly running

Directory Structure Requirements

Critical: Maintain this directory structure:

td/
├── import_modules.py          # Module loader script
├── mcp_webserver_base.tox     # Main TouchDesigner component
└── modules/                   # Python modules directory
    ├── mcp/                   # MCP core logic
    ├── utils/                 # Shared utilities
    └── td_server/             # Generated API server code

Available Tools and Features

Tools for AI Agents

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 a Python script in TouchDesigner
`get_td_class_details`	Gets details of a TouchDesigner Python class/module
`get_td_classes`	Gets a list of TouchDesigner Python classes
`get_td_info`	Gets information about the TouchDesigner environment
`get_td_node_parameters`	Gets parameters of a specific node
`get_td_nodes`	Gets nodes under a parent path, with optional filtering
`update_td_node_parameters`	Updates parameters of a specific node

Prompts

Prompt Name	Description
`Search node`	Fuzzy searches for nodes by name, family, or type
`Node connection`	Provides instructions to connect nodes
`Check node errors`	Checks for errors on a node and its children

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "touchdesigner" '{"command":"node","args":["/path/to/your/node_modules/touchdesigner-mcp-server/dist/index.js","--stdio"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect