🎛️ touchdesigner-agent-mcp

A premium, open-source Model Context Protocol (MCP) server that empowers LLMs (like Claude) to directly control, introspect, and build TouchDesigner networks in real-time.

With this server, an AI coding agent can create and connect operators, query parameters, capture the viewport to see what it built, automatically fix compile errors, and stream real-time data from TouchDesigner CHOPs.

---

🏗️ Architecture

This repository uses a zero-dependency, dual-process architecture:

┌─────────────────────────────────┐
│     Claude / MCP Host           │
└────────────────┬────────────────┘
                 │
                 │ MCP (stdio)
                 ▼
┌─────────────────────────────────┐
│     touchdesigner-agent-mcp (Python Client) │
└────────────────┬────────────────┘
                 │
                 │ HTTP (POST /mcp)
                 ▼
┌─────────────────────────────────┐
│  TouchDesigner Web Server DAT   │ (Installed via td/install.py)
└────────────────┬────────────────┘
                 │
                 ▼
┌─────────────────────────────────┐
│     TouchDesigner Operators     │
└─────────────────────────────────┘

The TouchDesigner side is built completely in plain Python (exposed via a Web Server DAT), meaning no binary .tox files or opaque components. You can read, audit, and diff every single line of code running in your project.

---

✨ Features

🔄 Dual-Directional Integration

• 25 Tools: Full CRUD for nodes, wiring, force-cooking, viewport rendering, and GLSL editing.
• 4 Prompt Templates: Guiding instructions that teach LLMs the best tool combinations for node finding, error handling, operator connections, and network repairs.
• 4 Resource Templates: Native MCP td:// resources that let the LLM stream live data from CHOP channels, node parameters, and project metadata.

🛡️ Undo Safety (Ctrl+Z)

Every single tool invocation that mutates TouchDesigner is automatically wrapped in a transaction block (ui.undo). If the agent makes a mistake, deletes a critical node, or wires something incorrectly, you can instantly revert it by pressing Ctrl+Z inside TouchDesigner.

⚡ Progress Tracking

Long-running operations (like scene scaffolding, viewport captures, and force-cooking) report real-time progress to the MCP client via the report_progress API, showing you exactly what the server is doing.

🔒 Zero-Config Security

On first installation, the installer auto-generates a secure, random Auth Token (secrets.token_urlsafe(32)) and binds it to the component. The token is preserved across reinstalls, keeping your TouchDesigner instance secure from unauthorized remote code execution (RCE).

---

🎛️ Tool Matrix

Category	Tools	Description
System Info	get_td_info, describe_td_tools	Inspect TouchDesigner build, OS, and available tool schemas.
Node CRUD	get_td_nodes, create_td_node, update_td_node_parameters, delete_td_node	Create, read, update, and delete operators.
Parameters & Errors	get_td_node_parameters, get_td_node_errors, exec_node_method	Read parameters, query errors, or trigger pulses/methods.
Python RCE	execute_python_script	Run arbitrary Python scripts directly inside the TouchDesigner execution context.
Introspection	get_td_classes, get_td_class_details, get_td_module_help	Let the LLM search TouchDesigner's Python API, docs, and help pages.
Visual Vision	td_viewport	Captures any TOP/COMP or the active network pane as an image (Base64 or file path).
Scene Scaffold	td_scaffold	Scaffold complete pipelines (Feedback Loop, Instancing, Render Setup) in one click.
Advanced Wiring	td_connect, td_layout	Family-validated operator wiring and automatic positioning without node overlaps.
GLSL & Files	td_glsl, td_save_tox, td_load_tox, td_save_project	Author GLSL shaders, import/export .tox assets, and save the .toe project.
Media Assets	td_list_media_assets	Scan local project directories for video, audio, images, and geometry assets.

---

📡 Resources

MCP Clients can read or subscribe to real-time resources using the td:// URI scheme:

URI Template	Resource Type	Description
td://chop/{path}	Dynamic CHOP Stream	Streams active float values for all channels in the target CHOP (e.g. td://chop/project1/lfo1).
td://node/{path}	Node Parameters	Lightweight read endpoint for parameters and operator metadata.
td://errors/{path}	Error State	Inspects compilation or wiring errors for the target node and its children.
td://project/info	Static Project Info	Metadata including project name, folder path, and the TouchDesigner app build.

---

🚀 Quick Start

1. Set Up TouchDesigner Side

1. Copy the td/ folder somewhere stable on your disk.
2. In TouchDesigner, open the Textport (Alt+T) and run the installer:

   import sys
   sys.path.append('/ABSOLUTE/PATH/TO/td')
   import install
   install.install()
   

3. This creates /project1/td_agent_mcp with a Web Server DAT running on port 9981.
4. Note the secure Auth Token printed in the Textport—you will need this for step 3.

[!TIP] If you make changes to the scripts in the td/ directory, you can reload and reinstall them instantly using: import importlib; importlib.reload(install); install.install()

---

2. Install the MCP Server

Build and run the server using uv (recommended):

# To run locally
uv sync
uv run touchdesigner-agent-mcp --stdio

---

3. Register the Server with Your Client

Claude Desktop

Add the server configuration to your claude_desktop_config.json:

{
  "mcpServers": {
    "touchdesigner-agent-mcp": {
      "command": "uv",
      "args": [
        "run", 
        "--directory", 
        "/ABSOLUTE/PATH/TO/touchdesigner-agent-mcp", 
        "touchdesigner-agent-mcp", 
        "--stdio"
      ],
      "env": {
        "TD_AUTH_TOKEN": "YOUR_AUTO_GENERATED_TOKEN_HERE"
      }
    }
  }
}

Claude Code (CLI)

Install the bundled marketplace plugin:

/plugin marketplace add axysar/touchdesigner-agent-mcp

---

⚙️ Configuration Reference

You can configure the client using environment variables or command-line flags:

Environment Variable	CLI Flag	Default	Description
TD_HOST	--td-host	127.0.0.1	The hostname/IP of the machine running TouchDesigner.
TD_PORT	--td-port	9981	The port of the Web Server DAT.
TD_AUTH_TOKEN	--td-token	(empty)	Security token matching the Authtoken parameter.
TD_TIMEOUT	--timeout	30	Request timeout in seconds.

---

🔒 Security Hardening

Because the server allows arbitrary Python execution inside TouchDesigner (giving the LLM full RCE capabilities on your local system), security is critical:

• Token Auth: All incoming HTTP requests require a valid Authorization: Bearer <token> header.
• Auto-Generation: If a token isn't manually specified, the installer automatically generates a cryptographically secure 32-character token.
• CORS Protection: The TouchDesigner Web Server DAT strictly rejects requests from arbitrary browser origins.
• Traversals: Asset scanning is restricted to a maximum depth of 5 levels to prevent system performance issues or directory leaks.

---

🛠️ Development & Contributing

See CLAUDE.md for quick-start development guidelines.

Running Tests

To run registration, schema validation, and resource-binding checks without requiring TouchDesigner to be active:

uv run pytest

Code Style

We use ruff to enforce linting and formatting standards:

uv run ruff check .
uv run ruff format .

---

📄 License & Attribution

This project is licensed under the MIT License — see LICENSE.

It synthesizes and extends two outstanding prior open-source works:

• @8beeeaaat/touchdesigner-mcp (Dual-process structure and baseline CRUD operations).
• @satoruhiga/claude-touchdesigner (TouchDesigner helper libraries).

TouchDesigner is a registered trademark of Derivative.