Skip to content
Back to search

touchdesigner-mcp

MCP server for TouchDesigner

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/8beeeaaat--touchdesigner-mcp/badge.svg)](/listings/8beeeaaat--touchdesigner-mcp)

HTML

<a href="/listings/8beeeaaat--touchdesigner-mcp"><img src="/api/listings/8beeeaaat--touchdesigner-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Tell the AI agent you already use:

> Set up https://github.com/8beeeaaat/touchdesigner-mcp

That's it. The full procedure lives in the **[Installation Guide](docs/installation.md)** — it opens with a table matching each AI app to its route, and everyone starts from *TouchDesigner Setup*. Or follow it yourself, step by step.

If 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)**.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 16 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "$schema": "https://www.schemastore.org/claude-code-marketplace.json",
  3. "name": "touchdesigner-mcp",
  4. "description": "TouchDesigner integration plugins for Claude Code",
  5. "owner": {
  6. "name": "sadao komaki",
  7. "email": "8beeeaaat@gmail.com"
  8. },
  9. "plugins": [
  10. {
  11. "name": "touchdesigner",
  12. "source": "./plugin/touchdesigner",
  13. "description": "Drives the touchdesigner-mcp server from Claude Code: bundles and preconfigures the server, adds launch/setup/debug/snapshot/overview/perf as slash commands, teaches the node-path and Python-lookup conventions its tools expect, and reminds Claude to verify every network mutation"
  14. }
  15. ]
  16. }
README.md · README · 124 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # TouchDesigner MCP
  2. [![Version](https://img.shields.io/npm/v/touchdesigner-mcp-server?style=flat&colorA=000000&colorB=000000)](https://www.npmjs.com/package/touchdesigner-mcp-server)
  3. [![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)
  4. This 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.
  5. [English](README.md) / [日本語](README.ja.md)
  6. ## Overview
  7. [![demo clip](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/particle_on_youtube.png)](https://youtu.be/V2znaqGU7f4?si=6HDFbcBHCFPdttkM&t=635)
  8. TouchDesigner MCP acts as a bridge between AI models and the TouchDesigner WebServer DAT, enabling AI agents to:
  9. - Create, modify, and delete nodes
  10. - Query node properties and project structure
  11. - Programmatically control TouchDesigner via Python scripts
  12. ## Installation
  13. Tell the AI agent you already use:
  14. > Set up https://github.com/8beeeaaat/touchdesigner-mcp
  15. That's it. The full procedure lives in the **[Installation Guide](docs/installation.md)** — it opens with a table matching each AI app to its route, and everyone starts from *TouchDesigner Setup*. Or follow it yourself, step by step.
  16. If 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)**.
  17. ## MCP Server Features
  18. This server enables AI agents to perform operations in TouchDesigner using the Model Context Protocol (MCP).
  19. ### Tools
  20. Tools allow AI agents to perform actions in TouchDesigner.
  21. | Tool Name | Description |
  22. | :---------------------- | :----------------------------------------------------------------- |
  23. | `create_td_node` | Creates a new node. |
  24. | `delete_td_node` | Deletes an existing node. |
  25. | `describe_td_tools` | Generates a manifest of the available TouchDesigner tools. |
  26. | `exec_node_method` | Calls a Python method on a node. |
  27. | `execute_python_script` | Executes an arbitrary Python script in TouchDesigner. |
  28. | `get_td_class_details` | Gets details of a TouchDesigner Python class or module. |
  29. | `get_td_classes` | Gets a list of TouchDesigner Python classes. |
  30. | `get_td_info` | Gets information about the TouchDesigner server environment. |
  31. | `get_td_module_help` | Gets Python help() documentation for TouchDesigner modules/classes.|
  32. | `get_td_node_errors` | Checks errors **and warnings** on a node and its descendants. Missing files, dangling references and shader failures are warnings, so no errors does not mean healthy. |
  33. | `get_td_node_parameters`| Gets the parameters of a specific node. |
  34. | `get_td_nodes` | Gets nodes under a parent path, with optional filtering. |
  35. | `get_top_image` | Captures the current output of a TOP node as an image. |
  36. | `update_td_node_parameters` | Updates the parameters of a specific node. |
  37. ### Prompts
  38. Prompts provide instructions for AI agents to perform specific actions in TouchDesigner.
  39. | Prompt Name | Description |
  40. | :------------------| :-------------------------------------------------------------------------- |
  41. | `Search node` | Fuzzy searches for nodes and retrieves information based on name, family, or type. |
  42. | `Node connection` | Provides instructions to connect nodes within TouchDesigner. |
  43. | `Check node errors`| Checks errors and warnings on a specified node, and recursively for its descendants. |
  44. ### Resources
  45. Not implemented.
  46. ## Developer Guide
  47. Looking for local setup, client configuration, project structure, or release workflow notes?
  48. See the **[Developer Guide](docs/development.md)** for all developer-facing documentation.
  49. ## Troubleshooting
  50. ### Troubleshooting version compatibility
  51. The 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.
  52. | API Server (component) | Condition | Behavior | Status |
  53. |------------------------|-----------|----------|--------|
  54. | = expected API version | Matches the shipped `.tox` | ✅ Works silently | Compatible |
  55. | ≥ minimum, < expected | Older component | ⚠️ "Update Recommended" notice appended to responses, continues | Warning |
  56. | > expected, same MAJOR | Newer component | ⚠️ Warning to update the MCP server, continues | Warning |
  57. | MAJOR above expected | Newer API generation | ❌ Execution stops — update the MCP server | Error |
  58. | < minimum (or missing) | Too old | ❌ Execution stops — update the component | Error |
  59. - **To resolve compatibility errors:**
  60. 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.
  61. 2. Delete the existing `touchdesigner-mcp-td` folder and replace it with the newly extracted contents.
  62. 3. Remove the old `mcp_webserver_base` component from your TouchDesigner project and import the `.tox` from the new folder.
  63. 4. Restart TouchDesigner and the AI agent running the MCP server (e.g., Claude Desktop).
  64. - **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.
  65. For a deeper look at how the MCP server enforces these rules, see [Version Compatibility Verification](docs/architecture.md#version-compatibility-verification).
  66. ### Troubleshooting connection errors
  67. - `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.
  68. - When the MCP server cannot reach TouchDesigner, you now get guided error messages with concrete fixes:
  69. - `ECONNREFUSED` / "connect refused": start TouchDesigner, ensure the WebServer DAT from `mcp_webserver_base.tox` is running, and confirm the configured port (default `9981`).
  70. - `ETIMEDOUT` / "timeout": TouchDesigner is responding slowly or the network is blocked. Restart TouchDesigner/WebServer DAT or check your network connection.
  71. - `ENOTFOUND` / `getaddrinfo`: the host name is invalid. Use `127.0.0.1` unless you explicitly changed it.
  72. - 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.
  73. - Once the underlying issue is fixed, simply run the tool again—the client clears the cached error and re-verifies the connection automatically.
  74. ## Contributing
  75. We welcome your contributions!
  76. 1. Fork the repository.
  77. 2. Create a feature branch (`git checkout -b feature/amazing-feature`).
  78. 3. Make your changes.
  79. 4. Add tests and ensure everything works (`npm test`).
  80. 5. Commit your changes (`git commit -m 'Add some amazing feature'`).
  81. 6. Push to your branch (`git push origin feature/amazing-feature`).
  82. 7. Open a pull request.
  83. Please always include appropriate tests when making implementation changes.
  84. ## License
  85. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.