Skip to main content
Glama

td-mcp

MCP (Model Context Protocol) server for controlling TouchDesigner from AI coding agents like Claude Code and Codex CLI.

Setup

1. TouchDesigner Side

  1. Install the callbacks file into your TD project:

    cd /path/to/your-td-project
    uvx td-mcp install
  2. Create a WebServer DAT in TouchDesigner

  3. Set Port to 9980

  4. Set the WebServer DAT's callbacks File parameter to td_mcp_callbacks.py

  5. Toggle Active ON

2. Agent Side

Claude Code (.mcp.json)

{
  "mcpServers": {
    "touchdesigner": {
      "command": "uvx",
      "args": ["td-mcp"],
      "env": {
        "TD_HOST": "127.0.0.1",
        "TD_PORT": "9980"
      }
    }
  }
}

Codex CLI

codex mcp add touchdesigner \
  --env TD_HOST=127.0.0.1 \
  --env TD_PORT=9980 \
  -- uvx td-mcp

Related MCP server: touchdesigner-mcp

Tools

Tool

Description

td_get_root

Get project root path (call first)

td_create_op

Create an operator

td_delete_op

Delete an operator

td_list_ops

List child operators

td_get_op_info

Get operator info

td_set_params

Set parameters (batch)

td_get_params

Get parameters (with schema discovery)

td_connect

Connect operators

td_disconnect

Disconnect operators

td_find_empty_space

Find empty space in network editor

td_execute

Execute Python code in TD

td_get_screenshot

Capture TOP screenshot

Environment Variables

Variable

Default

Description

TD_HOST

127.0.0.1

TouchDesigner host

TD_PORT

9980

WebServer DAT port

TD_TIMEOUT

10.0

Request timeout (seconds)

Architecture

AI Agent → MCP Server (stdio) → HTTP Client → TouchDesigner WebServer DAT

Security Note

td_execute allows arbitrary Python execution inside TouchDesigner. Use only in trusted local environments.

License

MIT

Available Tools

12 tools
td_connectC

Connect two operators.

Args: from_op: Source operator path to_op: Destination operator path from_index: Output connector index on source (default 0) to_index: Input connector index on destination (default 0)

Inputs: to_op (required), from_op (required), to_index, from_index.

td_create_opA

Create a new operator in TouchDesigner.

Args: parent: Parent path (e.g. "/project1") op_type: TD operator class name (e.g. "noiseCHOP", "constantTOP", "textDAT") name: Optional name for the new operator params: Optional dict of parameters to set immediately after creation nodeX: Optional X position in the network editor. Use td_find_empty_space to get a non-overlapping position. nodeY: Optional Y position in the network editor. Use td_find_empty_space to get a non-overlapping position.

Inputs: parent (required), op_type (required), name, nodeX, +2 more.

td_delete_opA

Delete an operator.

Args: path: Full path of the operator to delete (e.g. "/project1/noise1")

Inputs: path (required).

td_disconnectA

Disconnect an operator's connector.

Args: path: Operator path connector: "input" or "output" (default "input") index: Connector index (default 0)

Inputs: path (required), index, connector.

td_executeC

Execute Python code inside TouchDesigner.

Args: code: Python code to execute in TD's main thread return_expression: Optional expression to evaluate and return after execution

Inputs: code (required), return_expression.

td_find_empty_spaceA

Find an empty (non-overlapping) position for a new operator in the network editor.

Returns nodeX, nodeY coordinates that can be passed directly to td_create_op.

Args: parent: Parent path to search in (e.g. "/project1") width: Estimated width of the new operator (default 200) height: Estimated height of the new operator (default 200) direction: Placement strategy — "right" (next to rightmost op), "below" (under bottommost op), or "grid" (find first free slot in grid scan) padding: Minimum gap between operators (default 50)

Inputs: parent (required), width, height, padding, +1 more.

td_get_op_infoA

Get info about an operator. Returns minimal fields by default for token efficiency.

Args: path: Operator path fields: Fields to return (default: name, type, family). Available: name, type, family, path, inputs, outputs, numChildren, comment, storage, tags, nodeX, nodeY

Inputs: path (required), fields.

td_get_paramsA

Get parameters from an operator. Returns only non-default values by default for token efficiency.

Args: path: Operator path names: Specific parameter names to retrieve (returns all values including defaults) pattern: Glob pattern to filter parameter names (e.g. "noise*") discover: If true, returns rich schema per parameter (value, default, type, min, max, page, menuNames). Use this to discover available parameter names and their types for an unfamiliar operator. page: Page number for paginated results (50 params per page)

Inputs: path (required), page, names, pattern, +1 more.

td_get_rootA

Get the actual project root path. Call this FIRST before using any other tool that requires a path.

Returns the path of the top-level project COMP (e.g. "/project1" or whatever the user named it). Do not assume "/project1" — always discover the real path with this tool.

Inputs: no named parameters.

td_get_screenshotA

Get a screenshot of a TOP operator as base64 image.

Args: path: Path to a TOP operator width: Output width in pixels (default 640, height auto-scaled) format: Image format — "jpeg" (default, smaller) or "png"

Inputs: path (required), width, format.

td_list_opsA

List child operators with optional filtering and pagination.

Args: path: Parent path to list children of family: Filter by family (CHOP, TOP, SOP, DAT, COMP, MAT) type_filter: Filter by specific type name fields: Fields to return per op (default: name, type, family) limit: Max results (default 50) offset: Skip first N results

Inputs: path (required), limit, family, fields, +2 more.

td_set_paramsA

Set multiple parameters on an operator in a single batch call.

Args: path: Operator path params: Dict of parameter names to values (e.g. {"roughness": 0.5, "seed": 42})

Inputs: path (required), params (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 12 tools

    Disambiguation5/5

    Each tool targets a distinct operation: delete, create, list, get info, set/get parameters, connect/disconnect, execute code, screenshot, and utility functions like find_empty_space and get_root. No overlapping purposes; the distinction between get_op_info and get_params is clear (metadata vs parameters).

    Naming Consistency4/5

    All tools use the td_ prefix and mostly follow a verb_noun pattern (e.g., td_delete_op, td_create_op, td_get_params). However, td_connect and td_disconnect lack a noun (they connect/disconnect operators, but the name omits the object), and td_get_root is a compound verb_noun but with a different structure. Minor inconsistencies.

    Tool Count5/5

    12 tools is well-scoped for a TouchDesigner server. It covers the essential operations without being overwhelming. Each tool serves a clear purpose and none appear superfluous.

    Completeness4/5

    The set covers core CRUD for operators, parameter management, connections, code execution, and screenshots. Minor gaps exist: no explicit rename or move operator tool, and no recursive list tool. However, these can be worked around (rename via delete+create, move implied by delete+create, recursion via repeated list_ops).

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers