Skip to main content
Glama
Sign In
touch-mcp

touch-mcp

by benoitliard
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

touch-mcp

Python 3.11+ License MIT

High-performance MCP server for TouchDesigner — live control via WebSocket from any MCP-compatible AI (Claude, etc.)

Claude/LLM ←── stdio (MCP) ──→ touch-mcp ←── WebSocket ──→ TouchDesigner (.tox)

Why touch-mcp

The most comprehensive MCP server for TouchDesigner available. Unlike simpler alternatives, touch-mcp offers:

  • Persistent WebSocket connection — every tool call is a lightweight message, not a full HTTP round-trip

  • 37 tools covering nodes, parameters, connections, data access, scripting, timeline, rendering, layout, and more

  • Batching — bundle multiple operations into a single round-trip with td_batch, critical for building complex networks fast

  • Auto-reconnection — survives TD restarts and network hiccups

  • Auto-positioning — new nodes are placed intelligently in the network editor

  • Full Python access — execute arbitrary Python inside TD with td_execute_script, with access to all operator types and globals

Related MCP server: td-mcp

Quick Start

1. Install touch-mcp

pip install touch-mcp

Or from source:

git clone https://github.com/benoitliard/touch-mcp.git
cd touch-mcp
pip install -e ".[dev]"

2. Install the TouchDesigner bridge component

Open TouchDesigner (2024+), then drag TouchMCPBridge.tox from the td/ folder into your project. The component starts a WebSocket server on port 9980 automatically.

For instructions on building the .tox from source, see td/BUILD_TOX.md.

3. Configure your MCP client

See the configuration sections below, then start a conversation — touch-mcp connects to TouchDesigner on first use.

Configuration

Claude Desktop

Add the following to your claude_desktop_config.json:

{
    "mcpServers": {
        "touchdesigner": {
            "command": "touch-mcp",
            "args": ["--td-port", "9980"]
        }
    }
}

The config file is located at:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Claude Code

Create or edit .mcp.json in your project root:

{
    "mcpServers": {
        "touchdesigner": {
            "command": "touch-mcp",
            "args": ["--td-host", "localhost", "--td-port", "9980", "--timeout", "30"]
        }
    }
}

Available Tools

37 tools organised by category.

Nodes

Tool

Description

td_create_node

Create a new operator node (auto-positioned in the network)

td_delete_node

Delete a node and all its children

td_list_nodes

List child nodes under a path, optionally filtered by family

td_get_node

Get detailed metadata for a node (type, position, connections)

td_copy_node

Copy a node with all its parameters to a new location

td_rename_node

Rename a node without destroying it

td_find_nodes

Search for nodes by name, type, or family recursively

td_get_errors

Get errors and warnings for a node (and optionally its children)

td_set_flags

Set display, render, and/or bypass flags on a node

Parameters

Tool

Description

td_get_parameters

Read current parameter values for a node

td_set_parameters

Set one or more parameter values on a node

td_get_parameter_info

Get parameter schema (style, range, menu options, defaults)

td_set_expression

Set a parameter to expression mode with a Python expression

td_pulse_parameter

Pulse a parameter (trigger reload, reset, etc.)

Connections

Tool

Description

td_create_connection

Wire two nodes together by output and input index

td_delete_connection

Disconnect a node's input or output connector

td_get_connections

List all wires entering and leaving a node

Data

Tool

Description

td_read_chop

Read channel sample data from a CHOP node

td_read_top

Read TOP metadata (resolution, aspect)

td_read_sop

Read point and primitive geometry from a SOP node

td_read_dat

Read text or table contents from a DAT node

td_write_dat

Write text or append rows to a DAT node

Scripts

Tool

Description

td_execute_script

Execute arbitrary Python inside the live TouchDesigner instance

td_class_list

List all TD Python classes available in the environment

td_class_detail

Inspect methods and properties of a TD Python class

td_module_help

Get help() output for any TD Python module

Timeline

Tool

Description

td_timeline_get

Get the current timeline state (frame, fps, range, loop)

td_timeline_set

Set one or more timeline properties (frame, fps, range, loop)

td_timeline_play

Start timeline playback

td_timeline_pause

Pause timeline playback

Render

Tool

Description

td_screenshot

Save a TOP's current frame as a PNG file on disk

td_export_render

Export a rendered TOP frame to a file on disk

Project

Tool

Description

td_project_info

Get project metadata (name, path, fps, TD build/version)

td_project_save

Save the project in place or to a new path

Layout

Tool

Description

td_set_node_position

Set network-editor x/y positions for one or more nodes

td_align_nodes

Evenly distribute nodes along a horizontal or vertical axis

Batch

Tool

Description

td_batch

Execute multiple operations in a single WebSocket round-trip

CLI Options

touch-mcp [OPTIONS]

Options:
  --td-host TEXT    TouchDesigner WebSocket host (default: localhost)
  --td-port INT     TouchDesigner WebSocket port (default: 9980)
  --timeout FLOAT   Per-request timeout in seconds (default: 30.0)
  --debug           Enable debug logging

Development

git clone https://github.com/benoitliard/touch-mcp.git
cd touch-mcp
pip install -e ".[dev]"
pytest

Static analysis:

ruff check src/

License

MIT

Tool Schema Changelog

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

Loading tool schema changelog…

    This server cannot be deployed

    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • TouchDesigner MCP

      8beeeaaat
      A
      license
      B
      quality
      A
      maintenance
      A Model Context Protocol server that enables AI agents to control and operate TouchDesigner projects through creation, modification, and querying of nodes and project structures.
      14
      1,411 npm
      627
      MIT

    • td-mcp

      tai5863
      A
      license
      A
      quality
      D
      maintenance
      MCP server for controlling TouchDesigner from AI coding agents like Claude Code and Codex CLI, enabling operator manipulation, parameter control, and screenshot capture.
      12
      14 PyPI
      MIT

    • TDPilot

      dreamrec
      A
      license
      B
      quality
      C
      maintenance
      An MCP server for TouchDesigner that lets AI agents inspect, build, wire, optimize, and stabilize live TD networks with 106 tools, plus a technique memory system for reusable patterns.
      100
      16
      MIT