{"id":15400,"library":"touchdesigner-mcp-server","title":"TouchDesigner MCP Server","description":"The `touchdesigner-mcp-server` package provides an implementation of a Model Context Protocol (MCP) server designed to enable AI agents to control and operate TouchDesigner projects programmatically. Functioning as a bridge between AI models and the TouchDesigner WebServer DAT, it allows agents to create, modify, and delete nodes, query project structures, and execute Python scripts within TouchDesigner. The current stable version is 1.4.7, with frequent minor releases as indicated by the recent version history. Key differentiators include its focus on AI agent integration via MCP, semantic versioning for compatibility with the TouchDesigner API server, and a comprehensive set of tools for granular control over TouchDesigner's visual programming environment, making it a powerful tool for generative art, interactive installations, and automated content creation. It ships with TypeScript types, facilitating robust development.","status":"active","version":"1.4.7","language":"javascript","source_language":"en","source_url":"https://github.com/8beeeaaat/touchdesigner-mcp","tags":["javascript","MCP Server","TouchDesigner","typescript"],"install":[{"cmd":"npm install touchdesigner-mcp-server","lang":"bash","label":"npm"},{"cmd":"yarn add touchdesigner-mcp-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add touchdesigner-mcp-server","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const startMCPServer = require('touchdesigner-mcp-server').startMCPServer;","symbol":"startMCPServer","correct":"import { startMCPServer } from 'touchdesigner-mcp-server';"},{"note":"Used for typing server configuration objects. Always import types using `import type` to avoid bundling unnecessary runtime code.","wrong":"import { MCPServerOptions } from 'touchdesigner-mcp-server';","symbol":"MCPServerOptions","correct":"import type { MCPServerOptions } from 'touchdesigner-mcp-server';"},{"note":"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.","wrong":"import { TDTool } from 'touchdesigner-mcp-server';","symbol":"TDTool","correct":"import type { TDTool } from 'touchdesigner-mcp-server/dist/types/tools';"}],"quickstart":{"code":"import { startMCPServer } from 'touchdesigner-mcp-server';\nimport type { MCPServerOptions } from 'touchdesigner-mcp-server';\n\nconst serverOptions: MCPServerOptions = {\n  port: process.env.MCP_SERVER_PORT ? parseInt(process.env.MCP_SERVER_PORT) : 8080,\n  tdWebServerHost: process.env.TD_WEB_SERVER_HOST ?? '127.0.0.1',\n  tdWebServerPort: process.env.TD_WEB_SERVER_PORT ? parseInt(process.env.TD_WEB_SERVER_PORT) : 9981,\n  logLevel: process.env.NODE_ENV === 'production' ? 'info' : 'debug',\n  // Add any other necessary configuration as per your environment\n};\n\nasync function main() {\n  try {\n    console.log('Starting TouchDesigner MCP Server...');\n    const server = await startMCPServer(serverOptions);\n    console.log(`MCP Server running on port ${server.port}, connected to TouchDesigner at ${server.tdWebServerHost}:${server.tdWebServerPort}`);\n\n    // Keep the server running\n    process.on('SIGINT', () => {\n      console.log('Shutting down MCP Server...');\n      server.close();\n      process.exit(0);\n    });\n    process.on('SIGTERM', () => {\n      console.log('Shutting down MCP Server...');\n      server.close();\n      process.exit(0);\n    });\n\n  } catch (error) {\n    console.error('Failed to start MCP Server:', error);\n    process.exit(1);\n  }\n}\n\nmain();","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.3.0"},{"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).","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"The MCP server failed to establish a connection with the TouchDesigner WebServer DAT.","error":"Error: connect ECONNREFUSED 127.0.0.1:9981"},{"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`.","cause":"The package `touchdesigner-mcp-server` is not installed or the import path is incorrect.","error":"Module not found: Can't resolve 'touchdesigner-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.","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.","error":"Error: API below minimum compatible version"}],"ecosystem":"npm"}