TouchDesigner MCP Server

Common errors

• Error: connect ECONNREFUSED 127.0.0.1:9981

  cause The MCP server failed to establish a connection with the TouchDesigner WebServer DAT.
  fix Ensure TouchDesigner is running, the `mcp_webserver_base.tox` component is imported and active, and the specified host/port (e.g., 127.0.0.1:9981) are correct and not blocked by a firewall.

• Module not found: Can't resolve 'touchdesigner-mcp-server'

  cause The package `touchdesigner-mcp-server` is not installed or the import path is incorrect.
  fix Run `npm install touchdesigner-mcp-server` or `yarn add touchdesigner-mcp-server`. If using global installation for CLI usage, ensure your PATH is configured correctly or use `npx touchdesigner-mcp-server`.

• Error: API below minimum compatible version

  cause The `touchdesigner-mcp-server` is attempting to connect to a TouchDesigner API server component (`mcp_webserver_base.tox`) that is older than the minimum required version for the current MCP server.
  fix Update the `mcp_webserver_base.tox` component within your TouchDesigner project to the latest version by downloading `touchdesigner-mcp-td.zip` from the latest release and replacing the old component.

Warnings

• breaking Major version mismatches between the MCP Server and the TouchDesigner API Server are not compatible and will cause the server to stop execution. For example, MCP Server 2.0.0 will not work with a 1.x.x API Server.
  Fix: Ensure that the major versions of `touchdesigner-mcp-server` and the `mcp_webserver_base.tox` component in TouchDesigner are compatible. Refer to the 'Troubleshooting version compatibility' table in the official documentation before updating.
• gotcha Correct installation requires importing the `mcp_webserver_base.tox` component into your TouchDesigner project. Failing to do so, or placing it incorrectly, will prevent the MCP server from connecting to and controlling TouchDesigner.
  Fix: Always follow the 'Installation Guide' in the official documentation, ensuring `mcp_webserver_base.tox` is correctly imported and running within your TouchDesigner project, typically at `/project1/mcp_webserver_base`.
• gotcha Minor version differences between the MCP Server and the TouchDesigner API Server can lead to warnings or missing features, even if basic compatibility is maintained. For instance, an older MCP minor version with a newer API might not expose all new features.
  Fix: For optimal functionality and to avoid warnings, keep both `touchdesigner-mcp-server` and the `mcp_webserver_base.tox` component updated to their latest compatible versions. Consult the 'Troubleshooting version compatibility' section for detailed status.
• gotcha The server relies on a live connection to TouchDesigner's WebServer DAT. Connection issues (e.g., `ECONNREFUSED`, `ETIMEDOUT`, `ENOTFOUND`) are common if TouchDesigner is not running, the `WebServer DAT` is not active, or port/host configurations are incorrect.
  Fix: Verify that TouchDesigner is running, the `mcp_webserver_base.tox` component is loaded and active, and the configured `tdWebServerHost` and `tdWebServerPort` in the MCP server match your TouchDesigner setup (default port is often 9981).

Install

• npm install touchdesigner-mcp-server npm
• yarn add touchdesigner-mcp-server yarn
• pnpm add touchdesigner-mcp-server pnpm

Imports

• startMCPServer
  wrong:

  const startMCPServer = require('touchdesigner-mcp-server').startMCPServer;

  correct:

  import { startMCPServer } from 'touchdesigner-mcp-server';

  While primarily run via CLI or AI agent configuration, the server exposes a programmatic entry point for advanced Node.js setups. `startMCPServer` is an inferred function for initiating the server.
• MCPServerOptions
  wrong:

  import { MCPServerOptions } from 'touchdesigner-mcp-server';

  correct:

  import type { MCPServerOptions } from 'touchdesigner-mcp-server';

  Used for typing server configuration objects. Always import types using `import type` to avoid bundling unnecessary runtime code.
• TDTool
  wrong:

  import { TDTool } from 'touchdesigner-mcp-server';

  correct:

  import type { TDTool } from 'touchdesigner-mcp-server/dist/types/tools';

  Represents the structure of a tool exposed by the MCP server. The exact path may vary; developers might need to inspect `node_modules` for precise type definitions if not directly exported from the root.

Quickstart

This quickstart demonstrates how to programmatically start the `touchdesigner-mcp-server` as a Node.js process, configuring its port and the target TouchDesigner WebServer DAT connection details. It includes basic error handling and graceful shutdown.

import { startMCPServer } from 'touchdesigner-mcp-server';
import type { MCPServerOptions } from 'touchdesigner-mcp-server';

const serverOptions: MCPServerOptions = {
  port: process.env.MCP_SERVER_PORT ? parseInt(process.env.MCP_SERVER_PORT) : 8080,
  tdWebServerHost: process.env.TD_WEB_SERVER_HOST ?? '127.0.0.1',
  tdWebServerPort: process.env.TD_WEB_SERVER_PORT ? parseInt(process.env.TD_WEB_SERVER_PORT) : 9981,
  logLevel: process.env.NODE_ENV === 'production' ? 'info' : 'debug',
  // Add any other necessary configuration as per your environment
};

async function main() {
  try {
    console.log('Starting TouchDesigner MCP Server...');
    const server = await startMCPServer(serverOptions);
    console.log(`MCP Server running on port ${server.port}, connected to TouchDesigner at ${server.tdWebServerHost}:${server.tdWebServerPort}`);

    // Keep the server running
    process.on('SIGINT', () => {
      console.log('Shutting down MCP Server...');
      server.close();
      process.exit(0);
    });
    process.on('SIGTERM', () => {
      console.log('Shutting down MCP Server...');
      server.close();
      process.exit(0);
    });

  } catch (error) {
    console.error('Failed to start MCP Server:', error);
    process.exit(1);
  }
}

main();