TouchDesigner MCP Server Installation Guide

Installation guide for TouchDesigner MCP across different AI agents and platforms.

Quick Start

Most users can get running quickly with the Claude Desktop bundle flow. Download both touchdesigner-mcp-td.zip and touchdesigner-mcp.mcpb from the latest release, import mcp_webserver_base.tox into your TouchDesigner project (project1/mcp_webserver_base is recommended), then double-click the .mcpb file to install it in Claude Desktop. The bundle automatically connects to TouchDesigner once the component is running.

Prerequisites
TouchDesigner Setup (Required for All Methods)
MCP Server Installation Methods
For Updates from Previous Versions
HTTP Transport Mode
Verification
Troubleshooting

Prerequisites

TouchDesigner (latest version recommended)
For NPM-based installations: Node.js 20.x or later (not required when you only use Claude Desktop with the MCP bundle)
For Docker-based installations: Docker and Docker Compose

TouchDesigner Setup (Required for All Methods)

This step is required regardless of which installation method you choose.

Download touchdesigner-mcp-td.zip from the latest release
Extract the ZIP file
Import mcp_webserver_base.tox into your TouchDesigner project
Place it at /project1/mcp_webserver_base (or your preferred location)

import.mov

⚠️ Most Important: Do not change the folder structure or move files within the folder. mcp_webserver_base.tox references the contents of modules/ using relative paths.

Directory Structure:

touchdesigner-mcp-td/
├── import_modules.py          # Module loader
├── mcp_webserver_base.tox     # Main component
└── modules/                   # Python modules
    ├── mcp/                   # Core MCP logic
    ├── utils/                 # Utilities
    └── td_server/             # API server code

You can verify successful setup by checking the Textport (Alt+T or Dialogs → Textport):

MCP Server Installation Methods

Choose one of the following installation methods based on your AI agent and preferences. They all assume your TouchDesigner project already contains the imported mcp_webserver_base.tox component from the previous section.

Method 1: MCP Bundle (Claude Desktop only)

Best for: Claude Desktop users who want the simplest installation experience.

Downloads

Download the following from the latest release:

TouchDesigner Components: touchdesigner-mcp-td.zip
MCP Bundle: touchdesigner-mcp.mcpb

Installation Steps

Prepare TouchDesigner
- Complete the TouchDesigner Setup once per project (import mcp_webserver_base.tox, keep the folder layout intact, verify via Textport).
Install the MCP Bundle
- Double-click the touchdesigner-mcp.mcpb file to install it in Claude Desktop
dxt.mov
Start Using
- The bundle automatically handles the TouchDesigner server connection once the component is running
- Restart Claude Desktop if the MCP server is not recognized
- Open the Claude Desktop MCP panel to confirm that touchdesigner-mcp is available

Method 2: NPM Package (Claude Code, Codex, and other MCP clients)

Best for: Users who want flexibility across different AI agents or need custom configuration.

Installation Prerequisites

Node.js 20.x or later installed
TouchDesigner components set up (see TouchDesigner Setup)

Once those prerequisites are in place, add the MCP server to your client using one of the following configurations.

For Claude Desktop

Edit your claude_desktop_config.json:

{
  "mcpServers": {
    "touchdesigner": {
      "command": "npx",
      "args": ["-y", "touchdesigner-mcp-server@latest", "--stdio"]
    }
  }
}

Optional: Add --host / --port arguments if TouchDesigner is not running on the defaults (http://127.0.0.1:9981).

For Claude Code

Run the following command:

claude mcp add -s user touchdesigner -- npx -y touchdesigner-mcp-server@latest --stdio

Or manually edit ~/.claude.json:

{
  "mcpServers": {
    "touchdesigner": {
      "command": "npx",
      "args": ["-y", "touchdesigner-mcp-server@latest", "--stdio"],
    }
  }
}

For Codex

Run the following command:

codex mcp add touchdesigner -- npx -y touchdesigner-mcp-server@latest --stdio

Or manually edit ~/.codex/config.toml:

[mcp_servers.touchdesigner]
command = "npx"
args = ["-y", "touchdesigner-mcp-server@latest", "--stdio"]

For Other MCP Clients

Any MCP-compatible client can use the NPM package via stdio transport:

Command: npx
Args: ["-y", "touchdesigner-mcp-server@latest", "--stdio"]
Optional Args: --host=<url>, --port=<number>

Add the optional flags only when TouchDesigner is not running on http://127.0.0.1:9981.

Method 3: Docker Container

Best for: Developers, CI/CD pipelines, or users who prefer containerized environments.

Docker Prerequisites

Docker and Docker Compose installed
TouchDesigner components set up (see TouchDesigner Setup)

Installation Steps

Clone the repository

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

Build the Docker image
```
make build
```
Start the container

Choose a transport configuration:

Option A: Streamable HTTP (spec)

setup_streamable_http_compressed.mov

Start the container with HTTP transport:
```
TRANSPORT=http docker-compose up -d
```

(Optional) Override the HTTP port or TouchDesigner host:

TRANSPORT=http \
MCP_HTTP_PORT=6280 \
TD_HOST=http://host.docker.internal \
docker compose up -d

Point your MCP client to the HTTP endpoint. For example:

Claude Code (native HTTP entry):

{
  "mcpServers": {
    "touchdesigner-http": {
      "type": "http",
      "url": "http://localhost:6280/mcp"
    }
  }
}

Claude Desktop (via mcp-remote):

{
  "mcpServers": {
    "touchdesigner-http": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:6280/mcp"
      ]
    }
  }
}

Confirm the container is healthy (container binds 0.0.0.0, Docker publishes to 127.0.0.1 by default):
```
curl http://localhost:6280/health
```

Option B: Stdio Passthrough

Start the container in stdio mode:
```
docker-compose up -d
```

Configure your client to exec into the container (Claude Desktop example):

{
  "mcpServers": {
    "touchdesigner-docker": {
      "command": "docker",
      "args": [
        "compose",
        "-f",
        "/path/to/your/touchdesigner-mcp/docker-compose.yml",
        "exec",
        "-i",
        "touchdesigner-mcp-server",
        "node",
        "dist/cli.js",
        "--stdio",
        "--host=http://host.docker.internal"
      ]
    }
  }
}

On Windows include the drive letter (for example C:\\path\\to\\touchdesigner-mcp\\docker-compose.yml).

For Updates from Previous Versions

If you are updating, please refer to the procedure in the Latest Release.

HTTP Transport Mode

TouchDesigner MCP Server can run as an HTTP endpoint for remote clients, browser-based integrations, or when you prefer not to rely on stdio. Treat this section as optional—only follow it if you need HTTP/SSE access instead of stdio. You can start HTTP mode directly from the Node.js CLI or inside the Docker container.

Starting in HTTP Mode

Start the container with HTTP transport

TRANSPORT=http docker-compose up -d

setup_streamable_http_compressed.mov

Using npm command

# Start HTTP server
# 127.0.0.1:6280/mcp
npm run http

setup_streamable_http_npm_compressed.mov

touchdesigner-mcp-server \
  --mcp-http-port=6280 \
  --mcp-http-host=127.0.0.1 \
  --host=http://127.0.0.1 \
  --port=9981

Configuration Options

Option	Description	Default
`--mcp-http-port`	HTTP server port (required for HTTP mode)	-
`--mcp-http-host`	Bind address (`0.0.0.0` in Docker entrypoint, `127.0.0.1` in CLI)	`127.0.0.1` (CLI)
`--host`	TouchDesigner WebServer host	`http://127.0.0.1`
`--port`	TouchDesigner WebServer port	`9981`

Security tip (Docker): the container binds to 0.0.0.0, but docker-compose.yml publishes 127.0.0.1:${MCP_HTTP_PORT} by default so the endpoint is loopback-only. If you intentionally expose it to your LAN/WAN, change the compose port mapping (for example "0.0.0.0:6280:6280") and protect it with a firewall/reverse proxy and authentication.

Health Check

curl http://localhost:6280/health

Expected response:

{
  "status": "ok",
  "timestamp": "2026-07-30T05:30:00.000Z"
}

Transport Differences

Feature	stdio	Streamable HTTP
Connection	Standard I/O	HTTP/SSE
Use Case	Local CLI / desktop tools	Remote agents, browser integrations
State Model	Single connection	Stateless (per-request)
Port Required	No	Yes

Verification

After installation:

Start TouchDesigner with the imported mcp_webserver_base.tox component
Start your AI agent (Claude Desktop / Claude Code / Codex / etc.)
Confirm the touchdesigner-mcp server appears in the agent UI

If it does not show up:

Restart the AI agent
Make sure TouchDesigner and the WebServer DAT are running
Review the logs for error messages

Example view inside an agent:

Troubleshooting

Version Compatibility Issues

The MCP server enforces semantic versioning. If you see a compatibility warning or error:

Repeat the steps in TouchDesigner Setup
Remove the old mcp_webserver_base component and import the updated .tox
Restart both TouchDesigner and your AI agent

See Troubleshooting version compatibility in the README for additional details.

Connection Issues

Refer to Troubleshooting connection errors in the README for guided error messages (ECONNREFUSED, ETIMEDOUT, ENOTFOUND, etc.).

Other Issues

Check GitHub Issues for known reports
Review the main README for more background information

For Developer Setup

Need developer-focused workflows? See the Developer Guide.

Navigation Menu

Uh oh!

TouchDesigner MCP Server Installation Guide

Quick Start

Table of Contents

Prerequisites

TouchDesigner Setup (Required for All Methods)

MCP Server Installation Methods

Method 1: MCP Bundle (Claude Desktop only)

Downloads

Installation Steps

Method 2: NPM Package (Claude Code, Codex, and other MCP clients)

Installation Prerequisites

For Claude Desktop

For Claude Code

For Codex

For Other MCP Clients

Method 3: Docker Container

Docker Prerequisites

Installation Steps

Option A: Streamable HTTP (spec)

Option B: Stdio Passthrough

For Updates from Previous Versions

HTTP Transport Mode

Starting in HTTP Mode

Start the container with HTTP transport

Using npm command

Configuration Options

Health Check

Transport Differences

Verification

Troubleshooting

Version Compatibility Issues

Connection Issues

Other Issues

For Developer Setup

Uh oh!

FilesExpand file tree

installation.md

Latest commit

History

installation.md

File metadata and controls

TouchDesigner MCP Server Installation Guide

Quick Start

Table of Contents

Prerequisites

TouchDesigner Setup (Required for All Methods)

MCP Server Installation Methods

Method 1: MCP Bundle (Claude Desktop only)

Downloads

Installation Steps

Method 2: NPM Package (Claude Code, Codex, and other MCP clients)

Installation Prerequisites

For Claude Desktop

For Claude Code

For Codex

For Other MCP Clients

Method 3: Docker Container

Docker Prerequisites

Installation Steps

Option A: Streamable HTTP (spec)

Option B: Stdio Passthrough

For Updates from Previous Versions

HTTP Transport Mode

Starting in HTTP Mode

Start the container with HTTP transport

Using npm command

Configuration Options

Health Check

Transport Differences

Verification

Troubleshooting

Version Compatibility Issues

Connection Issues

Other Issues

For Developer Setup