tdmcp — TouchDesigner MCP server

MindDesigner (tdmcp) — TouchDesigner MCP 服务

tdmcp 是一个面向 TouchDesigner 的 Model Context Protocol（MCP）服务——用自然语言构建 TouchDesigner。你向 AI 助手（Claude、Claude Code、Cursor、Codex）描述想要的视觉效果；AI 会在你的项目中实际构建节点网络、检查错误，并向你展示预览。

“用噪声创建一个带有模糊和置换效果的反馈隧道，然后添加泛光并输出到窗口。”

……节点便会出现在你的 /project1 中，并完成连线。

它之所以可行，是因为它结合了其他工具都缺少的两项能力：

• 真实知识——内嵌了 629 个运算符、68 个 Python 类、工作流模式、GLSL 技术和教程的参考资料，因此 AI 使用的是真实的 TouchDesigner 运算符，而不是凭空猜测。
• 真实执行——一个运行在 TouchDesigner 内部的小型桥接程序，能够实际创建、连接、检查和预览节点，并通过“创建 → 验证 → 预览”循环让 AI 查看并修正自己的工作。每个生成的网络都会自动排列成易读的从左到右布局。

📖 文档

完整指南和参考资料请访问文档网站 → https://pantani.github.io/tdmcp/

🇧🇷 葡萄牙语文档： https://pantani.github.io/tdmcp/pt/

工作原理

你的电脑上有三个部分相互通信：

   You + your AI            tdmcp server               TouchDesigner
  (Claude / Cursor)   ─▶   (a small program)    ─▶   (the bridge inside TD)
   "make a feedback                                      builds real nodes
    tunnel from noise"                                   in /project1

1. 你的 AI 助手——你在这里输入想要的效果。
2. tdmcp 服务——一个小型 Node 程序，为 AI 提供一组 TouchDesigner“工具”和运算符知识库。只需安装一次。
3. 桥接程序——一个在 TouchDesigner 内部运行的小型组件，让服务能够实际操控它。每台机器只需启用一次。

所需内容

• TouchDesigner — 免费的非商业版即可。
• 支持 MCP 的 AI 助手：Claude Desktop（最简单）、Claude Code、Codex 或 Cursor。

只有从源代码构建时才需要 Node.js（Node 20+）。 一键安装的 Claude Desktop 扩展无需额外依赖——服务已打包在 .mcpb 扩展文件中。

开始使用

需要设置两端：AI（让它获取 tdmcp 工具）和 TouchDesigner（让 AI 能够控制它）。

🤖 最简单 — 让 AI 帮你安装。 使用 Claude Code、Codex 或 Cursor？粘贴这条消息即可：

Install and connect tdmcp for me using the official install guide:
https://pantani.github.io/tdmcp/guide/install
Do every step yourself; only stop when you need me to do the TouchDesigner bridge step.

它会克隆、构建并完成所有配置；唯一需要手动操作的是将一行代码粘贴到 TouchDesigner 中（见下方第 2 步）。

🟢 Claude Desktop — 一键安装 .mcpb（无需终端或 Node）。 下载 tdmcp.mcpb， 然后在 Claude Desktop 中打开 Settings → Extensions 并安装（拖入文件，或选择 Install from file）。主机和端口保持为 127.0.0.1 / 9980。完整操作指南： 安装指南。

🛠️ Claude Code / Codex / Cursor — 从源代码构建。

git clone https://github.com/Pantani/tdmcp.git
cd tdmcp
npm run setup   # installs, builds, and prints the exact line to connect your client

在 TouchDesigner 中启用桥接（所有用户）

最简单 — 无需使用 Textport。 从最新版本下载 tdmcp_bridge_package.tox， 将其拖入 /project1 网络，然后点击组件上的 Install。该包会自动完成初始化并在 端口 9980 上启动桥接。✅

import urllib.request; exec(urllib.request.urlopen("https://github.com/Pantani/tdmcp/raw/v0.13.2/td/bootstrap.py").read().decode())

无论使用哪种方式，都安全且可撤销——它只会添加一个简洁的组件；之后可运行 from mcp import install; install.uninstall() 将其移除。其他安装方式（模块路径、 终端、Palette 包）请参阅 桥接文档。

创作内容

打开 TouchDesigner 并连接 AI 后，用日常语言提出请求：

“创建一个响应音频的粒子星系，并显示预览。”

AI 会构建网络、检查错误并返回缩略图。还可以继续调整： “让色调暖一些”、“添加反馈拖尾”、“全屏输出。” 更多灵感请参阅 提示词手册。

无法连接？ 最常见的两个解决方法：确认桥接已启动 （curl http://127.0.0.1:9980/api/info 会返回 JSON），并在添加服务后 重启 AI 客户端。完整的 故障排除指南。

可以做什么

三层共 508 个工具，另有基础原语、CLI 自动化、库与打包、AI 会话记忆以及 Obsidian 知识库集成——从一行代码即可生成的艺术家工具（create_feedback_network、create_audio_reactive、create_particle_system、 create_generative_art，……），到构建模块（create_control_panel、 animate_parameter、用于 OSC/MIDI/DMX/NDI 的 create_external_io，……），再到 原子级节点增删改查和检查。许多系统开箱即可运行，并附带可调整、 设置预设或映射到控制器的控制面板。请参阅完整且持续更新的 工具参考和 配方集。

可选：创意 RAG

本地、可选启用的创意素材库，包含采用开放许可的艺术作品、艺术家和技法，供 AI 搜索以获取灵感。默认关闭。素材库不是策略——不提供 bridge、DMX 或 Python 执行功能。设置 TDMCP_RAG_ENABLED=1 并在本地安装 Ollama 后，运行 tdmcp creative-rag {sync|index|search}。 完整指南：docs/CREATIVE_RAG.md。

安全

bridge 会在 TD 进程中运行任意 Python 代码，并在所有网络接口上的端口 9980 进行监听——请将其视为通向该机器的一扇敞开大门。仅在可信网络中运行；对于不可信网络，请启用 bridge 身份验证（TDMCP_BRIDGE_TOKEN）和/或禁用执行端点（TDMCP_BRIDGE_ALLOW_EXEC=0）。详情： 安全。

链接与社区

• Glama MCP 目录 — tdmcp 的条目：https://glama.ai/mcp/servers/Pantani/tdmcp
• awesome-touchdesigner — 由社区整理的 TouchDesigner 列表：https://github.com/monkeymonk/awesome-touchdesigner
• 文档站点 — https://pantani.github.io/tdmcp/ · 路线图 — docs/ROADMAP.md

贡献与开发

使用 npm install && npm run build 构建；运行 npm test、npm run typecheck、npm run lint。使用 npm run docs:dev 编写文档（工具参考由 scripts/gen-tool-docs.ts 生成）。请参阅 CONTRIBUTING.md、CHANGELOG.md 和路线图。

许可证

MIT — 详见 LICENSE。