TouchDesigner MCP Server

Control TouchDesigner with AI through natural language. This MCP (Model Context Protocol) server lets Claude create operators, set parameters, execute Python, build node graphs, and more — all inside a running TouchDesigner project.

One-Click Install

Download the latest .mcpb bundle and double-click to install in Claude Desktop:

touchdesigner-mcp-1.0.0.mcpb (1.3 MB)

Double-click to install. No terminal commands, no configuration files. You still need to set up the TouchDesigner side — see TouchDesigner Setup below.

---

Quick Start

There are three things to set up: the TD server, the Node.js proxy, and your Claude config. If you used the one-click install above, skip to step 1 (TouchDesigner Setup) — the proxy is already configured.

1. TouchDesigner Setup (the server)

This is the most important part. You need to run a small Python server inside TouchDesigner that listens for commands from Claude.

Step 1: Open TouchDesigner

Open TouchDesigner (2023 or newer) and create or open a project. You should see the default /project1 container in the network editor.

Step 2: Set up the server (choose one method)

Option A: Plugin Installer (Recommended) — creates a self-contained COMP you can save as a .tox and reuse in any project.

1. Clone the repo:

   git clone https://github.com/superdwayne/Touchdesigner-mcp.git

2. Open the Textport (Dialogs → Textport and DATs) and run one of these:

   If your .toe file is saved inside the repo folder (easiest):

   exec(open(project.folder + '/td_mcp_plugin_installer.py').read())

   Otherwise, use the full path to where you cloned the repo:

   exec(open('/Users/yourname/Touchdesigner-mcp/td_mcp_plugin_installer.py').read())

3. A td_mcp_server Base COMP appears in /project1 with custom parameters:

   • Port — server port (default 8053)
   • Auto Start — starts the server on project open (default ON)
   • Start / Stop / Reload — pulse buttons for manual control

4. Save as reusable plugin: Right-click the COMP → Save Component .tox Next time, just drag the .tox into any project — no installer needed, no repo required.

5. Save your .toe file to keep the plugin in this project.

Tip: The server code is embedded inside the COMP. The .tox is fully self-contained — you can share it with others and it works without the repo.

---

Option B: Auto-Bootstrap — a lighter approach. The server loads and starts automatically every time you open your project.

1. In TouchDesigner, Tab → DAT → Execute to create an Execute DAT

2. Open the file td_mcp_bootstrap.py from this repo and copy its entire contents

3. Double-click the Execute DAT and paste it in

4. Set REPO_PATH to where you cloned this repo on your machine, e.g.:

   • macOS: '/Users/yourname/Documents/Touchdesigner-mcp'
   • Windows: r'C:\Users\yourname\Documents\Touchdesigner-mcp'

   Tip: If you save your .toe file inside the repo folder, you can leave REPO_PATH empty — it auto-detects!

5. In the Execute DAT parameters (right panel), toggle Start → On and Exit → On

6. Save your .toe file

That's it! Every time you open the project, the server starts automatically. No Textport commands needed.

To start it right now without reopening:

op('/project1/mcp_bootstrap').module.onStart()

---

Option C: Manual Setup — paste the server code directly and start via the Textport.

1. Tab → DAT → Text to create a Text DAT (e.g., text1)
2. Open td_mcp_server_auso_v2.py from this repo, copy the entire contents, and paste into the Text DAT
3. Open the Textport (Dialogs → Textport and DATs) and run:

op('/project1/text1').module.start_mcp_server(op('/project1/text1'))

Replace text1 with the actual name of your Text DAT if different.

You should see:

Starting MCP server on http://127.0.0.1:8053 (DAT: /project1/text1) ...
MCP Server started successfully.

Step 3: Verify it's running

Open a browser and visit: http://localhost:8053/api/status

You should get a JSON response confirming the server is active.

Stopping the server

The server stops automatically when you close TouchDesigner.

To stop manually, run in the Textport:

# Option A (Plugin):
op('/project1/td_mcp_server').Stop()

# Option B (Bootstrap):
op('/project1/mcp_server').module.stop_mcp_server()

# Option C (Manual):
op('/project1/text1').module.stop_mcp_server()

Restarting after an error

If you get Address already in use, stop the server first then start it again:

# Option A (Plugin) — handles it automatically, or:
op('/project1/td_mcp_server').Stop()
op('/project1/td_mcp_server').Start()

For Options B/C, save your project and restart TouchDesigner.

Warnings you can safely ignore

On startup you may see warnings like:

Warning: audioDeviceInCHOP not available in this TouchDesigner version
Warning: lutTOP not available in this TouchDesigner version

These are normal — some operator types don't exist in every TD build. The server skips them gracefully and works fine without them.

---

2. Node.js Proxy Setup

The proxy sits between Claude and TouchDesigner, translating MCP messages into HTTP calls.

Step 1: Clone and install

git clone https://github.com/superdwayne/Touchdesigner-mcp.git
cd Touchdesigner-mcp/td-mcp-proxy
npm install

Step 2: Find your absolute path to index.js

You'll need the full path to td-mcp-proxy/index.js on your computer. Run this to get it:

cd Touchdesigner-mcp/td-mcp-proxy
pwd

This will print something like:

• macOS: /Users/yourname/Projects/Touchdesigner-mcp/td-mcp-proxy
• Windows: C:\Users\yourname\Projects\Touchdesigner-mcp\td-mcp-proxy

Your full path to index.js is that output + /index.js. For example: /Users/yourname/Projects/Touchdesigner-mcp/td-mcp-proxy/index.js

Copy this path — you'll paste it into the Claude config in the next step.

You don't need to run the proxy manually — Claude Desktop launches it automatically.

---

3. Claude Desktop Configuration

Step 1: Open the config file

Open your Claude Desktop configuration file in a text editor:

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

If the file doesn't exist, create it.

Step 2: Add the TouchDesigner MCP server

Paste this into the config file, replacing the path with the one you copied in step 2 above:

{
  "mcpServers": {
    "TouchDesigner": {
      "command": "node",
      "args": ["/YOUR/ACTUAL/PATH/TO/Touchdesigner-mcp/td-mcp-proxy/index.js"],
      "env": {
        "TRANSPORT": "stdio",
        "TD_SERVER_URL": "http://localhost:8053"
      }
    }
  }
}

Example (macOS):

{
  "mcpServers": {
    "TouchDesigner": {
      "command": "node",
      "args": ["/Users/dwayne/Projects/Touchdesigner-mcp/td-mcp-proxy/index.js"],
      "env": {
        "TRANSPORT": "stdio",
        "TD_SERVER_URL": "http://localhost:8053"
      }
    }
  }
}

Example (Windows):

{
  "mcpServers": {
    "TouchDesigner": {
      "command": "node",
      "args": ["C:\\Users\\dwayne\\Projects\\Touchdesigner-mcp\\td-mcp-proxy\\index.js"],
      "env": {
        "TRANSPORT": "stdio",
        "TD_SERVER_URL": "http://localhost:8053"
      }
    }
  }
}

Do not use /path/to/ literally. You must replace it with the real path on your computer.

Step 3: Restart Claude Desktop

Quit and reopen Claude Desktop for the config to take effect.

Alternative: SSE Transport

If you prefer SSE transport, start the proxy manually:

cd /path/to/Touchdesigner-mcp/td-mcp-proxy
TRANSPORT=sse node index.js

Then use this config instead:

{
  "mcpServers": {
    "TouchDesigner": {
      "transport": "sse",
      "serverUrl": "http://localhost:8050/sse"
    }
  }
}

---

Startup Checklist

Every time you want to use this:

1. Open TouchDesigner with your project
2. If using the Plugin (Option A): the server starts automatically — check the Textport for MCP Server started successfully.
3. If using Manual Setup (Option C): open the Textport and run:

   op('/project1/text1').module.start_mcp_server(op('/project1/text1'))

4. Open Claude Desktop — it connects to the proxy automatically
5. Start talking to Claude about your TouchDesigner project

---

Features

• Create operators with smart auto-positioning, auto-wiring, and natural name resolution ("webcam", "blur", "mic")
• Delete operators (with protection for critical paths)
• Get/Set parameter values (case-insensitive lookup, expression support)
• Set Many parameters in a single batch
• List operators, children, parameters, and available types
• Execute Python code directly inside TouchDesigner
• Connect Nodes in sequence, parallel, or custom patterns
• Auto-Connect two nodes with smart type-based routing
• Build Workflows from presets (audio, interactive installation, 3D render scene)
• Layout networks into clean grids grouped by family
• Show Preview by opening operator viewers
• Timeline control (play, pause, set frame/FPS/range)
• CHOP Export bindings for audio-reactive and data-driven visuals
• Custom Parameters on COMPs for user-facing controls
• Node Styling with colors, comments, and tags

Example Commands

Once connected, just talk naturally to Claude:

create a circle
create a text TOP with message "Hello World"
list all components in /project1
set /project1/circle1 radius 0.5
list parameters of /project1/noise1
create a webcam input and connect it to a blur
build me an audio experience
execute python: result = [c.name for c in op('/project1').children]

Auto-connect

• auto_connect (default true) — wires new nodes to the most recent same-family sibling
• connect_source — explicit source operator path
• connect_parameter — input name (input1) or parameter name for connection
• family — hint (TOP/CHOP/SOP/DAT/COMP/MAT) to disambiguate ambiguous types

Workflow Presets

Use build_workflow for instant node graphs:

• audio_experience — Audio Device In → Out CHOP with viewer
• interactive_installation — Movie File In → Out TOP with viewer
• render_scene — Geometry + SOP, Phong MAT, Camera, Light, Render TOP

Natural Type Names

Use common names — the server resolves them:

Family	Aliases
TOP	blur, feedback, switch, null, circle, noise, ramp, level, composite, webcam, movie, image
CHOP	mic, lfo, constant, math, filter, lag, timer, keyboard, mouse, osc, midi
SOP	sphere, box, grid, torus, transform, merge, boolean, polyextrude
COMP	geometry/geo, camera/cam, light, container, base, window
MAT	phong, pbr, material
DAT	text, table, script, json, webclient

Add the family suffix if ambiguous (e.g., "transform SOP" vs "transform TOP").

---

Environment Variables

Variable	Default	Description
TD_MCP_PORT	8053	Port the Python server listens on inside TouchDesigner
TD_SERVER_URL	http://localhost:8053	URL the proxy uses to reach the TD server
TRANSPORT	stdio	Proxy transport mode: stdio or sse
PORT	8050	Port for SSE transport mode
TD_MCP_PROTECTED_PATHS	(none)	Comma-separated operator paths to protect from deletion

Troubleshooting

Server won't start in TouchDesigner

• Make sure you pasted the entire contents of td_mcp_server_auso_v2.py into the Text DAT
• Make sure you're calling start_mcp_server() with the DAT reference — just running the script (op('text1').run()) only loads the code, it doesn't start the server
• Check the Textport for error messages
• Verify port 8053 isn't already in use

Claude can't connect

• Confirm the TD server is running: visit http://localhost:8053/api/status in a browser
• Check your claude_desktop_config.json has the correct path to index.js
• Restart Claude Desktop after config changes
• Check the proxy log at /tmp/td-mcp-debug.log

Port conflicts

Change the TD server port with the TD_MCP_PORT environment variable and update TD_SERVER_URL in your Claude config to match.

Architecture

Claude Desktop  ←→  MCP Proxy (Node.js, stdio/SSE)  ←→  TD HTTP Server (Python, port 8053)  ←→  TouchDesigner

The proxy translates MCP JSON-RPC messages into HTTP calls to the Python server running inside TouchDesigner. The Python server uses run() to dispatch all TD API calls on the main thread and returns structured results back through the chain.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.