TouchDesigner MCP

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

英语/日本语

概述

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

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

用法

需要安装 Docker 或 Node.js

1.克隆存储库：

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

2.设置环境文件并构建：

在构建 Docker 镜像之前，复制模板文件并根据需要调整 TD_WEB_SERVER_HOST 和 TD_WEB_SERVER_PORT。

cp dotenv .env
make build

3. 在您的 TouchDesigner 项目中安装 API 服务器：

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

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

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

4. 启动 MCP 服务器容器

docker-compose up -d

5. 配置您的 AI 代理以使用 Docker 容器：

Claude Desktop 示例

{
  "mcpServers": {
    "touchdesigner": {
      "command": "docker",
      "args": [
        "compose",
        "-f",
        "/path/to/your/touchdesigner-mcp/docker-compose.yml",
        "exec",
        "-i",
        "touchdesigner-mcp-server",
        "node",
        "dist/index.js",
        "--stdio"
      ]
    }
  }
}

在 Windows 系统上，包括驱动器号，如 C:，例如C:\\path\\to\\your\\touchdesigner-mcp\\docker-compose.yml

要直接从 Node.js 使用预构建的 JS：

1. 安装软件包

mkdir some && cd ./some  # If you need a new directory
npm install touchdesigner-mcp-server

2. 在您的 TouchDesigner 项目中安装 API 服务器：

启动 TouchDesigner，并将some/node_modules/touchdesigner-mcp-server/td/mcp_webserver_base.tox组件直接导入到您想要控制的 TouchDesigner 项目下。例如：将其放置为/project1/mcp_webserver_base

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

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

3.配置您的AI代理：

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"
    }
  }
}

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

3.验证连接

如果 MCP 服务器被识别，则设置完成。如果无法识别，请尝试重新启动 AI 代理。如果启动时出现错误，请先启动 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`	检查指定节点的错误，如果有子节点则递归检查。

资源

未实施

对于开发人员

构建客户端和 API 服务器代码

cp dotenv .env
调整.env文件中的TD_WEB_SERVER_HOST和TD_WEB_SERVER_PORT以匹配您的开发环境
运行make build或npm run build重新生成代码

当您需要反映构建的代码时，请重新启动 MCP 服务器和 TouchDesigner。

验证 API 服务器

npm run test运行 MCP 服务器代码的单元测试，并与 TouchDesigner 进行集成测试。您可以通过从 TouchDesigner 菜单打开 Textport 来查看通信日志。
npm run dev启动@modelcontextprotocol/inspector 来调试各种功能。

项目结构概述

├── 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 ）
打开拉取请求

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

执照

麻省理工学院

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

模型上下文协议服务器，使 AI 代理能够通过创建、修改和查询节点和项目结构来控制和操作 TouchDesigner 项目。

Related MCP Servers

Appwrite MCP Serverofficial
appwrite
A
security
A
license
A
quality
A Model Context Protocol server that allows AI assistants to interact with Appwrite's API, providing tools to manage databases, users, functions, teams, and other resources within Appwrite projects.
Last updated -
84
48
Python
MIT License
SupaUI MCP Server
buoooou
A
security
F
license
A
quality
A Model Context Protocol server that enables AI agents to generate, fetch, and manage UI components through natural language interactions.
Last updated -
3
680
4
TypeScript
MCP Android Agent
nim444
-
security
A
license
-
quality
A Model Context Protocol server that enables AI agents to control and automate Android devices through natural language, supporting actions like app management, UI interactions, and device monitoring.
Last updated -
16
Python
MIT License
Agentic Tools MCP Server
Pimzino
A
security
A
license
A
quality
A Model Context Protocol server providing AI assistants with comprehensive project, task, and subtask management capabilities with project-specific storage.
Last updated -
29
108
50
TypeScript
MIT License

View all related MCP servers

TouchDesigner MCP