Registry / llm-agents / touchdesigner-mcp-server

touchdesigner-mcp-server

library1.4.7jsnpmunverified

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.

llm-agents ai-ml

npm install touchdesigner-mcp-server

github ↗package ↗

INSTALL

IMPORT

SIG · TOUCHDESIGNER-MCP-

touchdesigner-mcp-server

llm-agentsjavascriptv1.4.7

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

startMCPServer

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

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

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

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

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

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

TDTool

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

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

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.

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();

Debug

Known issues

breakingMajor 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.

affects: >=1.0.0

gotchaCorrect 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`.

affects: >=1.0.0

gotchaMinor 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.

affects: >=1.3.0

gotchaThe 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).

affects: >=1.0.0

Errors

Common errors & fixes

Error: connect ECONNREFUSED 127.0.0.1:9981

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'

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

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.

Upgrade

Version history

1.4.7latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

49 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/8beeeaaat/touchdesigner-mcp ↗

packagehttps://www.npmjs.com/package/touchdesigner-mcp-server ↗