TD-MCP

TD-MCP

MCP server + web dashboard for TouchDesigner. Inspect, optimize, and control TD patches from Claude Code or the browser.

Claude Code <--MCP(stdio)--> td-mcp server <--HTTP--> TD WebServer DAT (port 9981)
                                  |
                          Web Dashboard (:8080)

Features

22 MCP tools across 4 groups:

| Group | Tools | |-------|-------| | Inspect | List ops, trace signal flow, read CHOP channels, read/set params | | Optimize | Cook time stats, find hotspots, find unused ops, suggest fixes | | Cleanup | Find bypassed ops, delete dead ops (dry-run default), validate network | | Templates | 5 CHOP recipes, DAW mapping generator (OSC + MIDI CC) |

Web dashboard (FastAPI + htmx):

• Live connection status
• Network health overview
• Cook time hotspot visualization
• Recipe browser with script preview
• Cleanup tool with dry-run
• Script runner with safety validation

Built-in CHOP recipes:

• audio_reactive_basic -- audio in > RMS > lag > math > null
• audio_fft_bands -- FFT > split low/mid/high bands
• lfo_modulator -- LFO with range mapping
• midi_cc_mapper -- MIDI CC > smooth > range > output
• osc_receiver -- OSC input for Bitwig/Ableton sync

Install

pip install -e ".[dev]"

Requires Python 3.10+.

Usage

MCP Server (for Claude Code)

td-mcp

Add to your Claude Code MCP config:

{
  "mcpServers": {
    "td-mcp": {
      "command": "td-mcp",
      "args": []
    }
  }
}

Web Dashboard

td-mcp-web

Opens at http://localhost:8080. Dark-themed, auto-polls TD status every 5s.

Or run directly:

uvicorn td_mcp.web:app --port 8080 --app-dir src

Tests

pytest

26 tests covering client, server, tools, safety, models.

TouchDesigner Setup

On the TD machine (Luci's side):

1. Create a WebServer DAT in your project
2. Set Port to 9981
3. Paste the contents of td/webserver_callbacks.py into the DAT's callbacks
4. Toggle Active ON

That's it. The MCP server and web dashboard connect to this endpoint.

Safety

All scripts executed in TD go through safety.py which blocks:

• File I/O, network, subprocess imports
• eval/exec/compile/__import__/run
• Dunder attribute access (__class__, __globals__, etc.)
• Encoding bypass attempts (hex/unicode/octal escapes, chr/ord)
• Max 10,000 chars per script

Project Structure

td-mcp/
  src/td_mcp/
    server.py          # FastMCP server -- 22 tools via stdio
    web.py             # FastAPI web dashboard
    td_client.py       # Async HTTP client to TD WebServer DAT
    safety.py          # Script validator
    models.py          # Pydantic models
    tools/
      inspect.py       # List ops, trace signal flow, read CHOPs
      optimize.py      # Cook time hotspots, find unused/dead-end ops
      cleanup.py       # Delete dead ops (dry-run default), validate network
      templates.py     # 5 built-in CHOP recipes + DAW mapping generator
  td/
    webserver_callbacks.py  # Drop-in for TD's WebServer DAT
  tests/
    test_models.py
    test_safety.py
    test_server.py
    test_td_client.py
    test_tools.py
  pyproject.toml

License

MIT