{
  "markdown": "# TouchDesigner MCP\n\n[![Version](https://img.shields.io/npm/v/touchdesigner-mcp-server?style=flat&colorA=000000&colorB=000000)](https://www.npmjs.com/package/touchdesigner-mcp-server)\n[![Downloads](https://img.shields.io/npm/dt/touchdesigner-mcp-server.svg?style=flat&colorA=000000&colorB=000000)](https://www.npmjs.com/package/touchdesigner-mcp-server)\n\nThis is an implementation of an MCP (Model Context Protocol) server for TouchDesigner. Its goal is to enable AI agents to control and operate TouchDesigner projects.\n\n[English](README.md) / [日本語](README.ja.md)\n\n## Overview\n\n[![demo clip](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/particle_on_youtube.png)](https://youtu.be/V2znaqGU7f4?si=6HDFbcBHCFPdttkM&t=635)\n\nTouchDesigner MCP acts as a bridge between AI models and the TouchDesigner WebServer DAT, enabling AI agents to:\n\n- Create, modify, and delete nodes\n- Query node properties and project structure\n- Programmatically control TouchDesigner via Python scripts\n\n## Installation\n\nPlease refer to the **[Installation Guide](docs/installation.md)**.\n\nIf you are updating, please refer to the procedure in the **[Latest Release](https://github.com/8beeeaaat/touchdesigner-mcp/releases/latest#for-updates-from-previous-versions)**.\n\n## MCP Server Features\n\nThis server enables AI agents to perform operations in TouchDesigner using the Model Context Protocol (MCP).\n\n### Tools\n\nTools allow AI agents to perform actions in TouchDesigner.\n\n| Tool Name                | Description                                                        |\n| :---------------------- | :----------------------------------------------------------------- |\n| `create_td_node`        | Creates a new node.                                                |\n| `delete_td_node`        | Deletes an existing node.                                          |\n| `describe_td_tools`     | Generates a manifest of the available TouchDesigner tools.         |\n| `exec_node_method`      | Calls a Python method on a node.                                   |\n| `execute_python_script` | Executes an arbitrary Python script in TouchDesigner.              |\n| `get_td_class_details`  | Gets details of a TouchDesigner Python class or module.            |\n| `get_td_classes`        | Gets a list of TouchDesigner Python classes.                       |\n| `get_td_info`           | Gets information about the TouchDesigner server environment.       |\n| `get_td_module_help`    | Gets Python help() documentation for TouchDesigner modules/classes.|\n| `get_td_node_errors`    | Checks for errors on a specified node and its children. |\n| `get_td_node_parameters`| Gets the parameters of a specific node.                            |\n| `get_td_nodes`          | Gets nodes under a parent path, with optional filtering.           |\n| `get_top_image`         | Captures the current output of a TOP node as an image.             |\n| `update_td_node_parameters` | Updates the parameters of a specific node.                     |\n\n### Prompts\n\nPrompts provide instructions for AI agents to perform specific actions in TouchDesigner.\n\n| Prompt Name         | Description                                                                 |\n| :------------------| :-------------------------------------------------------------------------- |\n| `Search node`      | Fuzzy searches for nodes and retrieves information based on name, family, or type. |\n| `Node connection`  | Provides instructions to connect nodes within TouchDesigner.                |\n| `Check node errors`| Checks for errors on a specified node, and recursively for its children.    |\n\n### Resources\n\nNot implemented.\n\n## Developer Guide\n\nLooking for local setup, client configuration, project structure, or release workflow notes?\nSee the **[Developer Guide](docs/development.md)** for all developer-facing documentation.\n\n## Troubleshooting\n\n### Troubleshooting version compatibility\n\nThe MCP server and the TouchDesigner component are versioned on **two independent axes**: the npm package version and the **API version** (the contract between the MCP server and the `.tox` component). Each release declares the API version it ships with (`expectedApiVersion`) and the minimum it supports (`minApiVersion`, currently 1.3.0). The connected component's API version is compared against those two values — **the npm package version itself never gates compatibility**, so updating the MCP server alone never invalidates a supported component.\n\n| API Server (component) | Condition | Behavior | Status |\n|------------------------|-----------|----------|--------|\n| = expected API version | Matches the shipped `.tox` | ✅ Works silently | Compatible |\n| ≥ minimum, < expected | Older component | ⚠️ \"Update Recommended\" notice appended to responses, continues | Warning |\n| > expected, same MAJOR | Newer component | ⚠️ Warning to update the MCP server, continues | Warning |\n| MAJOR above expected | Newer API generation | ❌ Execution stops — update the MCP server | Error |\n| < minimum (or missing) | Too old | ❌ Execution stops — update the component | Error |\n\n- **To resolve compatibility errors:**\n  1. Download the latest [touchdesigner-mcp-td.zip](https://github.com/8beeeaaat/touchdesigner-mcp/releases/latest/download/touchdesigner-mcp-td.zip) from the releases page.\n  2. Delete the existing `touchdesigner-mcp-td` folder and replace it with the newly extracted contents.\n  3. Remove the old `mcp_webserver_base` component from your TouchDesigner project and import the `.tox` from the new folder.\n  4. Restart TouchDesigner and the AI agent running the MCP server (e.g., Claude Desktop).\n\n- **For developers:** When developing locally, run `npm run version` after editing `package.json` (or simply use `npm version ...`). This keeps the Python API (`pyproject.toml` + `td/modules/utils/version.py`), `mcpCompatibility.expectedApiVersion`, MCP bundle manifest, and registry metadata in sync so that the runtime compatibility check succeeds.\n\nFor a deeper look at how the MCP server enforces these rules, see [Version Compatibility Verification](docs/architecture.md#version-compatibility-verification).\n\n### Troubleshooting connection errors\n\n- `TouchDesignerClient` caches failed connection checks for **60 seconds**. Subsequent tool calls reuse the cached error to avoid spamming TouchDesigner and automatically retry after the TTL expires.\n- When the MCP server cannot reach TouchDesigner, you now get guided error messages with concrete fixes:\n  - `ECONNREFUSED` / \"connect refused\": start TouchDesigner, ensure the WebServer DAT from `mcp_webserver_base.tox` is running, and confirm the configured port (default `9981`).\n  - `ETIMEDOUT` / \"timeout\": TouchDesigner is responding slowly or the network is blocked. Restart TouchDesigner/WebServer DAT or check your network connection.\n  - `ENOTFOUND` / `getaddrinfo`: the host name is invalid. Use `127.0.0.1` unless you explicitly changed it.\n- The structured error text is also logged through `ILogger`, so you can check the MCP logs to understand why a request stopped before hitting TouchDesigner.\n- Once the underlying issue is fixed, simply run the tool again—the client clears the cached error and re-verifies the connection automatically.\n\n## Contributing\n\nWe welcome your contributions!\n\n1. Fork the repository.\n2. Create a feature branch (`git checkout -b feature/amazing-feature`).\n3. Make your changes.\n4. Add tests and ensure everything works (`npm test`).\n5. Commit your changes (`git commit -m 'Add some amazing feature'`).\n6. Push to your branch (`git push origin feature/amazing-feature`).\n7. Open a pull request.\n\nPlease always include appropriate tests when making implementation changes.\n\n## License\n\nMIT\n",
  "bytes": 7725,
  "sha": "8ae947df517697b5c11468c4667fee0952414785fffac3bb3c890420e4aa9df6",
  "repo_slug": "8beeeaaat/touchdesigner-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_8beeeaaat_touchdesigner_mcp_se_97880fde/readme"
}