TouchDesigner ↔ MCP bridge

Local bridge that lets an AI agent read and build real TouchDesigner networks: create operators, wire them, set parameters and expressions, lay the network out, validate it, look at the rendered result as an image, and iterate on what it sees.

Works with any MCP-compatible host — Claude Code, Claude Desktop, Cursor, Antigravity, VS Code Copilot, Windsurf, Cline, Zed, Gemini CLI, Codex CLI. Nothing in the server is vendor-specific; it imports only mcp and httpx.

→ Connecting an AI agent — per-host setup, verified.

python docs/verify_stdio.py     # proves the server works with any MCP host

1. What this is

your AI agent
    │  MCP over stdio
    ▼
C:\td-claude-mcp\server.py            ← separate Python 3.11 venv
    │  HTTP POST http://127.0.0.1:9980/mcp
    ▼
TouchDesigner Web Server DAT  (mcp_webserver)
    │
    ▼
mcp_callbacks  (td_webserver_callback.py)
    │
    ▼
TouchDesigner Python API → your live project

Two hard rules the design keeps:

• The MCP server never imports TouchDesigner. It only speaks HTTP.

• The TouchDesigner side never needs a pip package. Standard library only.

Only TouchDesigner itself ever mutates the network, so nothing can get out of sync.

No fake capabilities. Every mutating tool re-reads the object from the live network after the change and returns what TouchDesigner actually holds — not what was requested. A reported success is a verified success.

Related MCP server: tdmcp

2. Architecture

HTTP protocol

POST /mcp
{"id": "...", "action": "...", "args": {...}}

→ {"ok": true,  "id": "...", "result": {...}, "error": null}
→ {"ok": false, "id": "...", "result": null,
   "error": {"type": "...", "message": "...", "details": {...}, "traceback": "..."}}

GET /health · GET /info · GET /api · GET /version

Error types: OperatorNotFound, OperatorTypeInvalid, ParameterNotFound, ParameterInvalid, ConnectionInvalid, ConnectorNotFound, UnsupportedOperation, TouchDesignerError, ValidationError, ProjectNotSaved, PreviewError, BatchError, PythonExecutionError, ServerUnavailable, TimeoutError.

3. Requirements

• Windows

• TouchDesigner 2025.32460 (developed and tested against this build)

• System Python 3.10+, 3.11 preferred — not TouchDesigner's Python

• Claude Code

• No Node.js. No Docker. No database. No cloud.

Python dependencies: mcp[cli]>=2.1.1 and httpx. That is all.

MCP SDK note. This bridge targets MCP Python SDK 2.x, where FastMCP was renamed to MCPServer (from mcp.server.mcpserver import MCPServer). Code copied from older FastMCP examples will not run here.

4. Installation

powershell -ExecutionPolicy Bypass -File C:\td-claude-mcp\install.ps1

Creates the directories, builds .venv, upgrades pip, installs requirements.txt, and verifies that every module imports and all 32 MCP tools register.

Rebuild the environment from scratch:

powershell -ExecutionPolicy Bypass -File C:\td-claude-mcp\install.ps1 -Recreate

5. TouchDesigner setup

One step:

Open TouchDesigner → press Alt+T for the Textport → paste the entire contents of C:\td-claude-mcp\td_bootstrap.py → press Enter.

Then press Ctrl+S to save the project, so the bridge operators persist.

The bootstrap creates, inside /project1:

It introspects the running build, sets only parameters that actually exist, and prints an exact manual instruction for anything it cannot set safely. It is idempotent — re-run it any time to refresh the callback code.

td_bootstrap.py is deliberately tiny: the Textport behaves like a Python REPL, where a blank line inside an indented block ends the block, so a large script cannot be pasted into it reliably. The stub reads and execs td_bootstrap_impl.py from disk instead, which also means re-running it always picks up the current bridge code.

Manual setup (if you prefer, or if the bootstrap reports a manual step)

1. Open TouchDesigner and create/open a project.

2. In /project1, create a Text DAT named mcp_callbacks.

3. Paste the entire contents of C:\td-claude-mcp\td_webserver_callback.py into it.

4. In /project1, create a Web Server DAT named mcp_webserver.

5. Set Port = 9980.

6. Set Callbacks DAT = mcp_callbacks.

7. If the DAT has a Local Address parameter, set it to 127.0.0.1.

8. Turn Active On.

9. Save the project (Ctrl+S).

6. Bootstrap verification

Invoke-RestMethod http://127.0.0.1:9980/health

Expected:

ok    id   result                                              error
--    --   ------                                              -----
True       @{status=ok; bridge_version=1.0.0; project=...}

Full self-test:

powershell -ExecutionPolicy Bypass -File C:\td-claude-mcp\start_test.ps1

7. Connect your AI agent

Full per-host instructions, including the hosts whose config shape differs: docs/agents.md.

Most hosts take this block — Claude Desktop, Cursor, Antigravity, Windsurf, Cline, Gemini CLI, JetBrains AI Assistant:

{
  "mcpServers": {
    "touchdesigner": {
      "command": "C:\\td-claude-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\td-claude-mcp\\server.py"]
    }
  }
}

Claude Code, from the CLI:

claude mcp add touchdesigner --scope user -- "C:\td-claude-mcp\.venv\Scripts\python.exe" "C:\td-claude-mcp\server.py"

Two hosts want a different shape — VS Code uses servers instead of mcpServers, Zed uses context_servers, and Codex CLI uses TOML. Those are written out in docs/agents.md.

Whatever the host: use the absolute path to .venv\Scripts\python.exe. The host does not inherit your shell's PATH or your active virtualenv, and it must never be pointed at TouchDesigner's own Python.

Restart the host afterwards — most read MCP config only at startup — then ask it: "Check the connection to TouchDesigner." It should call td_status.

To check the server independently of any host:

python docs\verify_stdio.py

8. First test

Ask Claude Code:

Build a simple visual system: Noise → Blur → Level. Configure it, lay it out neatly, check for errors and show me a preview.

Claude should inspect, create, connect, configure, lay out, validate, preview, fix anything broken, and report what it changed.

9. Available tools

Connection — td_status, td_get_project_info

Inspection — td_list_operators, td_find_operators, td_inspect_operator, td_get_network_graph, td_list_operator_types

Parameters — td_get_parameters, td_get_parameter, td_set_parameter, td_set_expression, td_reset_parameter, td_pulse_parameter

DAT text — td_get_text, td_set_text

Creation — td_create_operator, td_delete_operator, td_rename_operator, td_move_operator, td_set_node_properties

Connections — td_connect, td_disconnect

Copy — td_copy_operator, td_copy_operators

Layout — td_layout (auto / horizontal / vertical / grid / native)

Validation & cook — td_validate_network, td_cook

Project — td_backup_project, td_save_project

Preview — td_preview

Escape hatch — td_execute_python

Batch — td_batch

10. Preview

td_preview(operator_path) force-cooks a TOP and returns a real MCP ImageContent block, so Claude can see the render and judge it, not just read a file path.

• TOP.saveByteArray() is used when available; otherwise the tool falls back to TOP.save() into previews\, reads the bytes back and deletes the file. The response reports which path was taken in method.

• Formats: png (default), jpg/jpeg, exr.

• Only TOPs can be previewed. For a CHOP/SOP/COMP result, wire it into a TOP (a Null TOP works) and preview that.

11. Backup

td_backup_project() writes a timestamped restore point into C:\td-claude-mcp\backups\ and never moves the live project.

Why it does not use project.save(path). TouchDesigner's own docstring for it is "Save the current session to disk", and project.name / project.folder are read-only properties that follow the save. Saving to a backup path therefore makes the backup the current project — the user's next Ctrl+S would land in the backups folder. This build offers no save-a-copy call, so backups are made two other ways instead.

mode selects one (snapshot / copy); the default auto does both and reports whatever succeeded. Existing backups are never overwritten. The response carries project_has_unsaved_changes plus a per-artifact includes_unsaved_changes, and warns when unsaved work is not covered.

Note that the true root / refuses COMP.save() ("Error creating file."), so the snapshot targets the configured root component (/project1) instead.

td_batch takes a backup automatically before any batch containing a delete.

If the project has never been saved there is no project.folder, so backup returns ProjectNotSaved and you must save the project once from the TouchDesigner UI first.

Saving

td_save_project() with no path saves in place. Passing a path is not a save-a-copy — it repoints the live project, so it is refused unless you also pass confirm_repoint=true. The response reports project_path_before, project_path_after and project_repointed.

12. Security

• The Web Server DAT in 2025.32460 has no bind-address parameter. Its parameters are pageindex, active, restart, port, callbacks, secure, privatekey, certificate, password, verifyclient, minprotocol plus the common DAT ones — there is no Local Address. The socket is therefore opened on 0.0.0.0 and that cannot be changed from the DAT.

  The bridge enforces loopback-only access itself instead: onHTTPRequest reads the request's clientAddress and refuses anything that is not on the loopback interface with 403 Forbidden, before the request reaches the dispatcher. Verified live — a request to the machine's LAN address is refused while 127.0.0.1 is served.

  GET /health reports the posture under security: enforced, client_address_key, rejected_requests and the request keys observed. If enforced is ever false, the client address could not be identified and requests are not being filtered — do not open port 9980 in the firewall.

• Do not open port 9980 in the Windows firewall.

• No password is stored in the source. Authentication is not needed for a loopback-only endpoint; if you add it later, put it in config.json.

• td_execute_python runs arbitrary Python inside TouchDesigner. It is reachable only over loopback, and it is documented to the model as an escape hatch of last resort.

• Protected paths (/, /project1, /local, /sys, /ui, /perform) and the bridge's own operators cannot be deleted without an explicit force.

• Deletion always requires confirm=true.

13. Troubleshooting

Logs: C:\td-claude-mcp\logs\mcp_server.log (stderr is mirrored there; stdout is reserved for the MCP protocol and stays clean).

14. Development

Run the tests:

cd C:\td-claude-mcp
& .\.venv\Scripts\python.exe -m unittest discover -s tests -t . -v

Static tests only (no TouchDesigner needed):

& .\.venv\Scripts\python.exe -m unittest discover -s tests -t . -p "test_[cehs]*.py"

Live integration test (creates and deletes __mcp_test_* operators only):

& .\.venv\Scripts\python.exe -m unittest tests.test_integration -v

Environment variables override config.json:

Multi-instance is prepared but not enabled in v1: add an instances block to config.json and select one with TD_INSTANCE. WebSocket transport is deliberately not implemented in v1; the action dispatcher is transport-agnostic so it can be added later without touching the tools.

15. Updating

After editing td_webserver_callback.py, push it into the running project without restarting TouchDesigner:

$body = @{ id = "reload"; action = "reload_callbacks"; args = @{} } | ConvertTo-Json -Compress
Invoke-RestMethod -Uri http://127.0.0.1:9980/mcp -Method Post -Body $body -ContentType application/json

Or ask Claude to run td_execute_python with the same action. Re-running td_bootstrap.py in the Textport does the same thing and also re-checks the Web Server DAT configuration.

After editing server.py, td_bridge.py or config.py, restart Claude Code — the MCP server process is launched by Claude and is only reloaded on restart.