TouchDesigner MCP Server for Projects, Node, Parameter Control

Overview

This MCP (Model Context Protocol) server provides a network-accessible bridge between TouchDesigner projects and external applications. It exposes a protocol to query project structure, inspect and modify node parameters, and subscribe to runtime updates so you can control TouchDesigner in real time from web apps, DAWs, controllers, or other automation systems.

Designed for developers and integrators, the server is useful when you need deterministic, scriptable control over TouchDesigner instances—whether for live performance, automated rendering, remote dashboards, or multi-machine setups. It simplifies instrumenting TouchDesigner projects by exposing nodes and parameters in a structured API and offering client-friendly message formats for common operations.

Features

• Expose TouchDesigner projects, node trees, and parameter metadata over a network API
• Read and write parameter values on individual nodes programmatically
• Query node hierarchies and project state (open/closed projects)
• Subscribe to parameter and node updates for real-time feedback
• Support for authentication and basic configuration (host, port, token)
• Example client snippets and utilities to integrate from Python, JavaScript, or command-line tools
• Lightweight server suitable for embedding in TouchDesigner or running alongside it

Installation / Configuration

Prerequisites: Python 3.8+ (or the runtime documented in the repo), Git, virtualenv (recommended).

Clone and install:

git clone https://github.com/8beeeaaat/touchdesigner-mcp.git
cd touchdesigner-mcp

# create and activate a virtualenv
python -m venv .venv
source .venv/bin/activate   # macOS/Linux
.\.venv\Scripts\activate    # Windows

# install dependencies
pip install -r requirements.txt

Basic configuration (example config.json):

{
  "host": "0.0.0.0",
  "port": 8765,
  "auth_token": "replace_with_secret_token",
  "log_level": "INFO"
}

Start the server (example CLI):

# default entrypoint (may vary; check repository README)
python -m mcp_server --config config.json

If the project supports running inside TouchDesigner as an extension or component, follow the repo examples to install the companion .tox or the extension script into your TouchDesigner project.

Authentication: The server supports token-based authentication (see config). All client requests should include the token using an Authorization header (Bearer token) or the transport’s recommended authentication mechanism.

Available Resources

• GitHub repository (source, examples, tests): https://github.com/8beeeaaat/touchdesigner-mcp
• Example clients: look in the /clients directory for Python/JS samples
• Example TouchDesigner components: /examples or /tox (if provided) to import directly
• API schema / message format: check /docs or /schema.json in the repo for concrete request/response definitions
• Issue tracker and discussions on the project GitHub for questions and bug reports

API Actions (Common)

The server provides a small set of high-level actions. Replace host, port, and token with your config.

Table: Common actions and payloads

Example set parameter (HTTP POST):

curl -X POST "http://localhost:8765/api/parameter/set" \
  -H "Authorization: Bearer replace_with_secret_token" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "default",
    "node_path": "/project1/geo1",
    "parameter": "tx",
    "value": 0.5
  }'

Example WebSocket subscribe (JSON message format):

{
  "action": "subscribe",
  "target": {
    "project": "default",
    "node_path": "/project1/geo1",
    "parameter": "tx"
  }
}

Server will reply with events when the parameter changes:

{
  "event": "parameter_changed",
  "target": { "node_path": "/project1/geo1", "parameter": "tx" },
  "value": 0.5,
  "timestamp": 1620000000.0
}

Use Cases

• Live visual performance: Connect a web-based control panel or MIDI/OSC controller to adjust node parameters on-the-fly (colors, transforms, shader uniforms) without opening TouchDesigner UI.
• Remote dashboards: Build a remote monitoring UI that lists projects and node states, and allows operators to toggle or tune parameters during events.
• Automated testing and rendering: Drive parameter sweeps from scripts to render sequences for automated content generation or QA of TouchDesigner networks.
• DAW / show control integration: Synch parameter changes to musical events or lighting cues by hooking the DAW/control system to the MCP server.
• Collaborative setups: Multiple operators or services can read the scene structure and propose or apply changes programmatically while preventing conflicting edits using server-side locking or validation workflows.