TouchDesigner MCP

这是 TouchDesigner 的 MCP（模型上下文协议）服务器的实现。目标是使 AI 代理能够控制和操作 TouchDesigner 项目。

英语/日语

概述

TouchDesigner MCP 充当 AI 模型和 TouchDesigner WebServer DAT 之间的桥梁，使 AI 代理能够：

创建、修改和删除节点
查询节点属性和项目结构
通过 Python 脚本以编程方式控制 TouchDesigner

用法

需要安装 Node.js

1.安装touchdesigner-mcp-server包

mkdir some && cd ./some （如果需要） npm install touchdesigner-mcp-server

2. 连接到 TouchDesigner

将 mcp_webserver_base.tox 放置在 TouchDesigner 中

启动 TouchDesigner，并将td/mcp_webserver_base.tox组件直接导入到您的 TouchDesigner 项目下。例如：将其放置为/project1/mcp_webserver_base

导入 tox 将触发td/import_modules.py脚本，该脚本加载 API 服务器控制器等模块。

您可以通过从 TouchDesigner 菜单打开 Textport 来检查启动日志。

3. 配置 TouchDesigner MCP 服务器

在 TouchDesigner 运行时，配置您的 AI 代理（Claude Desktop、Cursor、VSCode CopilotChat 等）以连接到 MCP 服务器。

例如：Claude Desktop

{
  "mcpServers": {
    "touchdesigner": {
      "args": [
        "/path/to/your/node_modules/touchdesigner-mcp-server/dist/index.js", // <-- Replace with the absolute path to node_modules/touchdesigner-mcp-server/dist/index.js
        "--stdio"
      ],
      "command": "node",
      "transportType": "stdio"
    }
  }
}

在 Windows 系统上，请包含驱动器号，例如 C: 例如C:\\path\\to\\your\\node_modules\\touchdesigner-mcp-server\\dist\\index.js

如果 MCP 服务器被识别，则设置完成。如果无法识别，请重新启动代理。如果启动时出现错误，请在启动 TouchDesigner 后尝试再次启动代理。如果 API 服务器在 TouchDesigner 中运行，代理可以通过提供的工具使用 TouchDesigner。

MCP 服务器功能

该服务器通过模型上下文协议（MCP）实现对TouchDesigner的操作，并提供各种实现文档的参考。

工具

工具允许 AI 代理在 TouchDesigner 中执行操作。

工具名称	描述
`create_td_node`	创建一个新节点。
`delete_td_node`	删除现有节点。
`exec_node_method`	在节点上调用 Python 方法。
`execute_python_script`	在 TD 中执行任意 Python 脚本。
`get_td_class_details`	获取 TD Python 类/模块的详细信息。
`get_td_classes`	获取 TouchDesigner Python 类的列表。
`get_td_info`	获取有关 TD 服务器环境的信息。
`get_td_node_parameters`	获取特定节点的参数。
`get_td_nodes`	获取父路径下的节点（可选过滤）。
`update_td_node_parameters`	更新特定节点的参数。

提示

提示为 AI 代理提供在 TouchDesigner 中执行特定操作的指令。

提示名称	描述
`Search node`	模糊搜索节点并根据名称、家族、类型检索信息。
`Node connection`	提供在 TouchDesigner 内连接节点的说明。
`Check node errors`	检查指定节点的错误，如果有子节点则递归检查。

资源

未实施

对于开发人员

构建 MCP 服务器代码

克隆存储库

git clone https://github.com/8beeeaaat/touchdesigner-mcp.git

安装依赖项

cd touchdesigner-mcp
npm install

设置环境文件并构建

# Copy the template and adjust TD_WEB_SERVER_URL as needed
cp dotenv .env

# Build the project (generates API client/server schemas and compiles MCP resources)
# Make sure the Docker daemon is running before executing this command
npm run build

TouchDesigner 设置

1.代码生成：

运行npm run build生成以下代码：

MCP 服务器代码
TouchDesigner WebServer DAT 的 API 服务器代码

2.将MCP服务器的WebServer导入TouchDesigner：

启动 TouchDesigner，并在项目下直接导入td/mcp_webserver_base.tox组件。导入 tox 将触发td/import_modules.py脚本，该脚本会加载 API 服务器控制器等模块。

3.验证API服务器运行：

确保td/modules目录中的 Python 模块可以从mcp_webserver_base组件访问。运行npm run test ，对 MCP 服务器代码和 TouchDesigner 连接执行单元测试和集成测试。您可以通过从 TouchDesigner 菜单打开 Textport 来检查通信日志。

您可以使用npm run dev通过 @modelcontextprotocol/inspector 进行调试。

提示： mcp_webserver_base.tox包含一个配置用于连接 MCP 服务器和 TouchDesigner 的 WebServer DAT。请确保此 DAT 处于活动状态，并在.env文件中TD_WEB_SERVER_URL指定的端口上运行（默认值： 9981 ）。要更改端口，请执行以下操作：

更改.env中的TD_WEB_SERVER_PORT
重新运行npm run build
更改 mcp_webserver_base (WebServer DAT) 中的端口并重新启动 DAT

与 MCP 兼容的 AI 代理连接

在 TouchDesigner 运行时，配置您的 AI 代理（Cursor、Claude Desktop、VSCode CopilotChat 等）以连接到 MCP 服务器。

例如：Claude Desktop

{
  "mcpServers": {
    "dev_touchdesigner": {
      "args": [
        "/path/to/your/touchdesigner-mcp/dist/index.js", // <-- Replace with the absolute path to /dist/index.js after build
        "--stdio"
      ],
      "command": "node",
      "transportType": "stdio"
    }
  }
}

在 Windows 系统上，请包含驱动器号，例如 C: 例如C:\\path\\to\\your\\touchdesigner-mcp\\dist\\index.js

设置后的项目结构

├── src/                       # MCP server source code
│   ├── api/                  # OpenAPI spec for TD WebServer
│   ├── core/                 # Core utilities (logger, error handling)
│   ├── features/             # MCP feature implementations
│   │   ├── prompts/         # Prompt handlers
│   │   ├── resources/       # Resource handlers
│   │   └── tools/           # Tool handlers (e.g., tdTools.ts)
│   ├── gen/                  # Code generated from OpenAPI schema for MCP server
│   ├── server/               # MCP server logic (connections, main server class)
│   ├── tdClient/             # TD connection API client
│   ├── index.ts              # Main entry point for Node.js server
│   └── ...
├── td/                        # TouchDesigner related files
│   ├── modules/              # Python modules for TouchDesigner
│   │   ├── mcp/              # Core logic for handling MCP requests in TD
│   │   │   ├── controllers/ # API request controllers (api_controller.py, generated_handlers.py)
│   │   │   └── services/    # Business logic (api_service.py)
│   │   ├── td_server/        # Python model code generated from OpenAPI schema
│   │   └── utils/            # Shared Python utilities
│   ├── templates/             # Mustache templates for Python code generation
│   ├── genHandlers.js         # Node.js script for generating generated_handlers.py
│   ├── import_modules.py      # Helper script to import API server modules into TD
│   └── mcp_webserver_base.tox # Main TouchDesigner component
├── tests/                      # Test code
│   ├── integration/
│   └── unit/
├── .env                        # Local environment variables (git ignored)
├── dotenv                      # Template for .env
└── orval.config.ts             # Orval config (TS client generation)

API 代码生成工作流程

本项目使用基于OpenAPI的代码生成工具（Orval/openapi-generator-cli）：

API 定义： Node.js MCP 服务器和 TouchDesigner 内部运行的 Python 服务器之间的 API 契约在src/api/index.yml中定义。

Python 服务器生成（ npm run gen:webserver ）：
- 通过 Docker 使用openapi-generator-cli 。
- 读取src/api/index.yml 。
- 根据 API 定义生成 Python 服务器框架 ( td/modules/td_server/ )。此代码通过 WebServer DAT 在 TouchDesigner 内部运行。
- 需要安装并运行 Docker。
Python 处理程序生成（ npm run gen:handlers ）：
- 使用自定义 Node.js 脚本（ td/genHandlers.js ）和 Mustache 模板（ td/templates/ ）。
- 读取生成的 Python 服务器代码或 OpenAPI 规范。
- 生成连接到td/modules/mcp/controllers/generated_handlers.py中的业务逻辑的处理程序实现（ td/modules/mcp/services/api_service.py ）。
TypeScript 客户端生成（ npm run gen:mcp ）：
- 使用Orval从openapi-generator-cli捆绑的模式 YAML 生成 API 客户端代码和 Zod 模式以进行工具验证。
- 生成 Node.js 服务器使用的类型化 TypeScript 客户端（ src/tdClient/ ）向 WebServer DAT 发出请求。

构建过程（ npm run build ）运行所有必要的生成步骤（ npm run gen ），然后进行 TypeScript 编译（ tsc ）。

贡献

欢迎您的贡献！

分叉存储库
创建功能分支（ git checkout -b feature/amazing-feature ）
进行更改
添加测试并确保一切正常（ npm test ）
提交您的更改（ git commit -m 'Add some amazing feature' ）
推送到你的分支（ git push origin feature/amazing-feature ）
打开拉取请求

在进行实施变更时，请始终包含适当的测试。

执照

麻省理工学院

TouchDesigner MCP

Integrations