TouchDesigner MCP Server

An MCP server for TouchDesigner that lets you control TouchDesigner with Claude (or any Model Context Protocol client). Create operators, set parameters, and wire networks inside a running TouchDesigner project just by describing what you want — "make a noise texture chained into a level" — and watch the operators appear in your patch.

Built for Claude Code but works with any MCP-compatible client (Cline, Continue, Claude Desktop, etc.).

  MCP Client  ──stdio──▶  server.js  ──HTTP :9980──▶  Web Server DAT  ─▶  /project1
  (Claude…)              (this repo)                  (inside TD)         (your network)

---

What you need

• macOS, Linux, or Windows (instructions are mac/linux; on Windows use the equivalent paths)
• Node.js 18 or newer — check with node -v. Install via brew install node or nodejs.org.
• TouchDesigner — any recent build, download here.
• Claude Code — npm install -g @anthropic-ai/claude-code, then run claude once to log in.

---

Setup — three steps

1. Get the MCP server running

git clone https://github.com/aliphi/touchdesigner-mcp.git
cd touchdesigner-mcp
npm install

That installs the two dependencies (@modelcontextprotocol/sdk, zod). Don't run node server.js yourself — Claude Code will start it for you in step 3.

2. Set up TouchDesigner to listen

Shortcut: open Touchdesigner/TouchdesignerClaudeMCP.toe — it's a ready-to-use TD project with the Web Server DAT already created, configured on port 9980, and wired to the callback below. Open it, make sure the Web Server DAT's Active toggle is on, and skip to step 3.

Otherwise, to set it up by hand in your own project:

1. Open TouchDesigner (a fresh project is fine — you'll be inside /project1).
2. Press Tab → DAT → Web Server to drop a Web Server DAT into the network.
3. In the DAT's parameters:
   • Set Port to 9980
   • Turn Active ON
4. Right-click the Web Server DAT → Edit Callbacks. A text editor opens.
5. Replace the entire contents of that callback file with the contents of td_webserver_callback.py from this repo. Save.

Verify it's working: open http://localhost:9980 in your browser. You should see:

{"status": "connected", "project": "project1"}

If you don't, the DAT isn't Active or the port isn't 9980. Fix that before continuing.

3. Register the MCP server with Claude Code

From inside the touchdesigner-mcp folder, run:

claude mcp add touchdesigner -- node "$(pwd)/server.js"

That's it — Claude Code now knows how to launch the server.

<details> <summary>Or, register it manually</summary>

Edit ~/.claude.json and add a touchdesigner entry under mcpServers:

{
  "mcpServers": {
    "touchdesigner": {
      "command": "node",
      "args": ["/absolute/path/to/touchdesigner-mcp/server.js"]
    }
  }
}

Replace /absolute/path/to/ with your real path. </details>

---

Try it

Make sure TD is open with the Web Server DAT active, then in any terminal run claude and try:

List what's in my TouchDesigner project

Create a noiseTOP feeding a levelTOP, then a compositeTOP

Build me a basic 3D scene: a sphere, a camera, a light, and a renderTOP that outputs it all

Claude will use the tools below to build the network inside your running TD project. Switch back to TD to watch the operators appear.

---

What the MCP server exposes

Tool	What it does
td_list_operators	List everything at a given path. Always run this first.
td_create_operator	Create a new operator (TOP/CHOP/SOP/DAT/COMP) at a position
td_set_parameter	Set a single parameter on an operator
td_connect	Wire one operator's output into another's input
td_run_python	Escape hatch — run arbitrary Python inside TD

Conventions Claude follows (defined in CLAUDE.md):

• Everything lives under /project1
• Operators spaced 200 horizontal × 150 vertical
• Sources on the left, outputs on the right

---

Repo layout

server.js                                  Node MCP server (the thing Claude launches)
td_webserver_callback.py                   Paste this into TD's Web Server DAT
CLAUDE.md                                  Conventions Claude follows when building networks
package.json                               Node deps
Touchdesigner/TouchdesignerClaudeMCP.toe   Ready-to-use TD project with the Web Server DAT pre-wired

---

Troubleshooting

"Error connecting to TouchDesigner: fetch failed" TD isn't reachable. Check, in order: (a) TD is open, (b) the Web Server DAT exists, (c) its port is 9980, (d) Active is on, (e) http://localhost:9980 returns the JSON above in your browser.

Claude says it doesn't have TouchDesigner tools The MCP server isn't registered. Run claude mcp list — touchdesigner should appear. If it doesn't, redo step 3 with an absolute path. After registering, fully quit and reopen Claude Code.

"Cannot find module '@modelcontextprotocol/sdk'" You skipped npm install. Run it inside the touchdesigner-mcp folder.

Operators get created but td_set_parameter errors with "no attribute 'par.foo'" That parameter name doesn't exist on that operator type. Ask Claude to use td_run_python with dir(op('/project1/x').par) to list valid parameters.

Port 9980 already in use Either kill whatever's using it (lsof -i :9980) or change the port in both server.js (the TD_PORT constant near the top) and the Web Server DAT in TD.

---

How it works under the hood

The MCP server has no domain logic — it serializes Python strings and POSTs them to http://localhost:9980. The Web Server DAT's callback tries eval(code) first, and if that's a SyntaxError, falls back to exec(code). The last expression in the script becomes the HTTP response body, which is why every built-in tool ends with an f-string summary like f"Connected {…} -> {…}".

Security note: the callback runs arbitrary Python with no auth. Keep localhost only — don't expose port 9980 to your network.