TouchDesigner MCP MCP — Use Cases, Install & Live Demo

Why use it

Key features

12 tools: create/delete node, set params, run Python, read errors, class/module introspection
Works via a WebServer DAT in TouchDesigner (bundled .tox)
Configurable port (default 9981), localhost-only by default
Python execution lets you reach anything TD exposes
Error inspection helps agents self-correct quickly

Live Demo

What it looks like in practice

touchdesigner-mcp.replay ▶ ready

0/0

Install

Pick your client

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

{
  "mcpServers": {
    "touchdesigner-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "touchdesigner-mcp-server"
      ],
      "env": {
        "TD_WEBSERVER_HOST": "127.0.0.1",
        "TD_WEBSERVER_PORT": "9981"
      }
    }
  }
}

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "touchdesigner-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "touchdesigner-mcp-server"
      ],
      "env": {
        "TD_WEBSERVER_HOST": "127.0.0.1",
        "TD_WEBSERVER_PORT": "9981"
      }
    }
  }
}

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "touchdesigner-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "touchdesigner-mcp-server"
      ],
      "env": {
        "TD_WEBSERVER_HOST": "127.0.0.1",
        "TD_WEBSERVER_PORT": "9981"
      }
    }
  }
}

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "touchdesigner-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "touchdesigner-mcp-server"
      ],
      "env": {
        "TD_WEBSERVER_HOST": "127.0.0.1",
        "TD_WEBSERVER_PORT": "9981"
      }
    }
  }
}

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json

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

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json

{
  "context_servers": {
    "touchdesigner-mcp": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "touchdesigner-mcp-server"
        ]
      }
    }
  }
}

Add to context_servers. Zed hot-reloads on save.

claude mcp add touchdesigner-mcp -- npx -y touchdesigner-mcp-server

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use TouchDesigner MCP

Scaffold a starter TouchDesigner patch from a brief

👤 Motion designers and visual engineers prototyping ⏱ ~30 min intermediate

When to use: You're starting a new patch and want the skeleton in place before hand-tuning.

Prerequisites

TouchDesigner running with mcp_webserver_base.tox loaded — Download the tox, drop into your project, set port 9981
API version ≥ 1.3.0 — Check TouchDesigner version

Flow

Describe the patch

Scaffold a generative visuals patch: audio-reactive particles (noise → instancing), post-processing bloom, 1080p output.✓ Copied

→ Agent creates a coherent node graph with the named operators
Fix errors

Report TD errors and fix them.✓ Copied

→ Uses get_td_node_errors, corrects params, iterates

Outcome: A working starter patch you tweak, instead of dragging from scratch.

Pitfalls

Agent invents operators that don't exist — Make it call get_td_classes first and stick to real class names

Combine with: filesystem

Sweep parameters and compare visual outputs

👤 Artists tuning looks ⏱ ~20 min intermediate

When to use: You want to explore a parameter range without clicking in the TD UI.

Flow

Describe the sweep

On noise1, sweep period=0.2,0.5,1.0,2.0 and harmonics=1,2,4. Snapshot each via renderpick1.✓ Copied

→ Uses update_td_node_parameters and execute_python_script for snapshot saves
Name the winner

I liked period=1.0 harmonics=2. Apply and save project.✓ Copied

→ Params set, project saved via python exec

Outcome: Faster iteration; the boring combinatorial click-work is gone.

Pitfalls

Long Python scripts blocking TD's main thread — Split into short run calls, or run inside an Execute DAT

Learn TouchDesigner's Python API by asking the agent

👤 Designers new to TouchDesigner's Python ⏱ ~10 min beginner

When to use: You're writing a Script CHOP/DAT and need to know which method to call.

Flow

Ask for the class

What methods exist on class 'Op' for walking children?✓ Copied

→ Agent calls get_td_class_details and returns real methods
See a runnable example

Show a short Python snippet that logs every descendant's path.✓ Copied

→ Snippet uses real API, not made-up methods

Outcome: Accurate Python examples grounded in the live TouchDesigner instance.

Combinations

Pair with other MCPs for X10 leverage

touchdesigner-mcp + filesystem

Save snapshots/renders to disk and reference them next turn

After each parameter set, save a PNG via renderpick1 to ~/td-snapshots/ and read back the manifest.✓ Copied

touchdesigner-mcp + xcodebuild

Render and package for macOS kiosk

Render an output and package as a macOS app bundle via xcodebuild.✓ Copied

touchdesigner-mcp + filesystem

Archive project states as git-trackable .toe exports

Export current project as a .toe and commit it.✓ Copied

Tools

What this MCP exposes

Tool	Inputs	When to call
create_td_node	parent_path, type, name?	Add a new operator
delete_td_node	path	Remove an operator
update_td_node_parameters	path, params map	Set one or many parameters on a node
get_td_nodes	filter?	Enumerate nodes matching a filter
get_td_node_parameters	path	Read current parameter values
get_td_node_errors	(none)	Find and fix problems in the current project
execute_python_script	script: str	Escape hatch for anything the other tools don't cover
exec_node_method	path, method, args	Call a specific method on a node (e.g., .cook())
get_td_classes	(none)	List available classes to pick from
get_td_class_details	class_name	Ground Python suggestions in real API surface
get_module_help	module_name	Retrieve module docstrings
get_td_info	(none)	Check TD version and server state

Cost & Limits

What this costs to run

API quota: None
Tokens per call: Small: node paths + small param maps
Monetary: Free; TouchDesigner license applies
Tip: Prefer update_td_node_parameters with a map instead of many single-param calls.

Security

Permissions, secrets, blast radius

Credential storage: No credentials

Data egress: HTTP to 127.0.0.1:<port>. Do not expose the WebServer DAT to the public network.

execute_python_script runs arbitrary Python inside your TouchDesigner process — treat it as remote code execution and use only with trusted prompts.
Exposing the WebServer DAT on 0.0.0.0 gives anyone on your LAN full control of your TD instance. Keep it bound to 127.0.0.1.

Troubleshooting

Common errors and fixes

ECONNREFUSED 127.0.0.1:9981

TouchDesigner isn't running or WebServer DAT isn't active. Open the tox and confirm it's active.

Verify: In TD console: op('mcpwebserver').par.active.eval()

API version too low

Upgrade TouchDesigner to a build where the API is ≥ 1.3.0.

Verify: Help → About TouchDesigner

Python execution silently fails

Check the TD textport for the traceback; some ops only cook when connected to a viewer.

Verify: Alt-T opens the textport

Alternatives

TouchDesigner MCP vs others

Alternative	When to use it instead	Tradeoff
unreal	You're driving Unreal Engine scenes, not TouchDesigner patches	Different runtime; different DCC
unity	Unity is your target engine	Different DCC entirely
godot-mcp-pro-2	Godot is your engine	Different DCC

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills