🎛️ 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.

Related MCP server: touchdesigner-mcp

✨ 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

📡 Resources

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

🚀 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.

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:

🔒 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.