TouchDesigner MCP 接入实战:让 AI 在节点工程里建节点、改参数、跑 Python
节点连连看的尽头,是让 AI 替你拉线
TouchDesigner 老手都懂一种疲惫:脑子里效果已经成型,手却要在几百个节点里翻参数、接连线、试错重调。touchdesigner-mcp(8beeeaaat/touchdesigner-mcp)把这件事交了出去——它在 TouchDesigner 的 WebServer DAT 上架一座桥,AI 客户端通过 MCP 协议直接对你的工程动手:建节点、改参数、跑 Python、看报错,甚至把画面拍下来给自己看。项目 MIT 开源,npm 包 touchdesigner-mcp-server 当前 Registry latest 为 2.1.0,选题登记的 1.2.0 一样可用。站内 AI 工具接入教程已覆盖画图、记忆、界面库几类,实时图形引擎这一块这是第一篇。
它适合谁:已经在用 TouchDesigner 做演出、展陈、装置或视觉内容,同时手里有 Claude Desktop、Claude Code、Codex 这类 AI 客户端的人。两者缺一,先补缺的那头再回来。
安装是两个半场,缺一半都白搭
官方安装指南开篇一句话定调:"Setup has two halves"——TouchDesigner 端放组件,AI 客户端端挂服务器,两半都做完链路才通。上半场四步,所有人一样:

上半场 TouchDesigner 端四步人人要做,下半场按客户端三选一;深色条是两半场的接头:9981 端口的 WebServer DAT
四步里有一步最容易踩雷:解压后不要动文件夹结构。官方加粗警告 mcp_webserver_base.tox 用相对路径引用 modules/ 里的 Python 模块,把文件挪个位置,组件就找不到自己的逻辑了。验证是否装好,开 Textport(Alt+T 或 Dialogs 菜单)看加载日志,官方在文档里放了对照截图。
下半场按你聊天的工具挑路。Claude Desktop 最省事:下载 touchdesigner-mcp.mcpb 双击安装,全程不碰终端。Claude Code 和 Codex CLI 用户建议装官方插件,插件除了打包这个服务器还带 /touchdesigner: 命令集与技能,一条命令完事:
claude plugin marketplace add 8beeeaaat/touchdesigner-mcp claude plugin install touchdesigner@touchdesigner-mcp codex plugin marketplace add 8beeeaaat/touchdesigner-mcp codex plugin add touchdesigner@touchdesigner-openai
其他 MCP 客户端走 npm 包手动挂,stdio 配置三行:
{
"mcpServers": {
"touchdesigner": {
"command": "npx",
"args": ["-y", "touchdesigner-mcp-server@latest"]
}
}
}
TouchDesigner 不在默认地址(http://127.0.0.1:9981)时加 --host= / --port= 参数。Docker 与 CI 环境有第三条路:仓库自带 docker-compose,TRANSPORT=http 起 Streamable HTTP 端点(默认 6280 端口,curl http://localhost:6280/health 探活),或 stdio 直通模式。官方文档明确 Node 版本要求 22.18+、24.x 或 26+,奇数版(23.x/25.x)不支持——npx 路线排错先查这个。
十四条工具,五份差事
服务器暴露 14 个工具和 3 个提示模板。工具全名单按差事归堆如下:

造与删/跑代码/看结构/查文档/拍快照五组,工具名与描述译自官方 README Tools 表
有几个工具值得单独点名。get_top_image 把 TOP 节点当前输出截成图像回传——这意味着 AI 能「看见」你画面长什么样,改完参数自己检查效果,而不是瞎改。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.
翻译过来:缺文件、悬空引用、shader 失败都归为警告而非错误,所以「没有 error」不等于健康——让 AI 排查时最好明确说连 warnings 一起看。
三个提示模板(Prompts)是写给 AI 的操作指引:Search node 按名字/家族/类型模糊搜节点,Node connection 教 AI 怎么接节点,Check node errors 递归查子孙节点的错误与警告。日常你不用直接调它们,AI 遇到对应任务会自己取用。
真跑一遍:两条报错比文档直观
2026-10-11 在 Linux 终端对 1.2.0 做了两次启动实测(本机无 TouchDesigner,恰好把启动链路的两道检查都撞见了):

不带 --stdio 被 CLI 守卫拦下;带上后服务器正常启动并自检 TouchDesigner 连接,报 ECONNREFUSED 引导信息
第一条报错值得展开:源码里 stdio 模式由 NODE_ENV=cli 或 --stdio 参数二选一开启,直接裸跑会命中"浏览器模式"守卫。README 的各客户端配置模板其实都替你带上了正确姿势,但如果你是自己写脚本拉起服务器,就会撞上这句迷惑性很强的提示——它说的 browser 并不是真的浏览器。第二条报错是启动自检在连 TouchDesigner 的 9981 端口:文案与 README「Troubleshooting connection errors」一节的 ECONNREFUSED 引导逐字一致——先开 TouchDesigner、确认 mcp_webserver_base 组件在跑、核对端口。两道检查都在服务器启动时同步完成,连不上就不提供工具,宁可 fail fast 不装死。
还有一个对排错很关键的设计:连接失败的判定结果会被缓存 60 秒(TouchDesignerClient 的实现),期间后续工具调用直接复用缓存错误,避免连环轰炸 TouchDesigner;修复底层问题后再调一次工具,缓存即清、自动重连。ETIMEDOUT 提示网络或性能问题,ENOTFOUND 多半是主机名写错——README 建议没有特殊需求就用 127.0.0.1。
版本兼容是双轴的,别只看包版本
这个项目有个不常见的版本设计:npm 包版本和 API 版本(服务器与 .tox 组件之间的契约)是两条独立的轴。每次发布都会声明 expectedApiVersion 与 minApiVersion(当前 1.3.0),连接时拿组件的 API 版本对照这两个值定行为——完全匹配则静默工作;组件偏旧则附「建议更新」提示继续跑;差距过大(跨大版本)直接停。README 加粗强调:npm 包版本本身从不管兼容性,所以只升级 MCP 服务器永远不会弄坏一个受支持的组件。真遇上兼容报错,官方给的修复动作是三步:下最新的 touchdesigner-mcp-td.zip、删旧组件文件夹换新的、在工程里移除旧 mcp_webserver_base 再导入新 .tox,然后重启 TouchDesigner 与 AI 客户端。
进了客户端之后怎么用
链路通了,用法就朴素了。举三个 README 认可的典型任务,对着工具表能看出 AI 会怎么拆解:
「帮我在 /project1 下建一个 Movie File In TOP 接 Noise,再接 Out」——AI 调 create_td_node 连建三个节点,用 Node connection 模板的知识接好线,再 get_td_nodes 回读确认。改造现有工程时它会先 get_td_nodes 摸清结构、get_td_node_parameters 读参数,然后才动手改——跟一个谨慎的人类协作者一样。「这个 COMP 为什么不出画面」——AI 从 get_td_node_errors 查起,顺着警告线索(纹理丢失、路径悬空)定位,必要时候 get_td_class_details 查 API 文档确认用法。
更彻底的玩法是直接放权:execute_python_script 能在 TouchDesigner 里执行任意 Python 脚本,op() 遍历、参数批改、外部数据拉取都能一行代码解决。能力上限等于 TouchDesigner 的 Python API 本身——这也是为什么要装 get_td_classes / get_td_module_help 这组查文档工具:AI 边查官方 API 文档边写代码,比背着一个静态模型知识库靠谱。官方仓库首页的演示视频就是这么干的:对着 YouTube 一段粒子效果,让 AI 在 TouchDesigner 里复现。
该知道的局限
Resources 接口官方明确 Not implemented,想通过 MCP 读工程资源树目前没门,一切靠工具组合。安装指南的路线表里,ChatGPT 桌面版用户需要额外装 Codex CLI,ChatGPT 网页版要走安全隧道的高级路径——OpenAI 系客户端的支持明显比 Claude 系绕。另外组件端的 WebServer DAT 默认无鉴权监听本机 9981 端口,官方在 Docker 文档里提醒过暴露到网络时要自备防火墙与认证,本机使用无所谓,多人共机或挂到内网就要留心。
来源与延伸
本文步骤、工具表与引文依据 8beeeaaat/touchdesigner-mcp 官方 README 与 docs/installation.md 整理;两次启动实测输出为 2026-10-11 于 Node 20.16 环境真实运行所得,版权归原作者所有。