tdmcp — TouchDesigner MCP server
Build real visual systems in TouchDesigner from plain language with Claude, Cursor or Codex.
Open source Open in the app JSON README (API)
About
Build real visual systems in TouchDesigner from plain language with Claude, Cursor or Codex.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- pantani
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.13.2
- Stars
- 39
- Forks
- 8
- Open pull requests
- 2
- Last push
- 2026-08-15T18:14:32Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:02:09
- Updated
- 2026-08-29 03:02:09
- Origin id
io.github.Pantani/tdmcp
README
# MindDesigner (tdmcp) — TouchDesigner MCP server
[](https://github.com/Pantani/tdmcp/actions/workflows/ci.yml)
[](https://pantani.github.io/tdmcp/)
[](https://www.npmjs.com/package/@dpantani/tdmcp)
[](https://nodejs.org)
[](https://modelcontextprotocol.io)
[](LICENSE)
[](https://glama.ai/mcp/servers/Pantani/tdmcp)
**tdmcp is a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server
for [TouchDesigner](https://derivative.ca)** — build TouchDesigner from plain
language. You describe a visual to an AI assistant (Claude, Claude Code, Cursor,
Codex); the AI builds the actual network of nodes inside your project, checks it
for errors, and shows you a preview.
> *"Create a feedback tunnel from noise with blur and displace, then add bloom and
> output it to a window."*
…and the nodes appear, wired up, in your `/project1`.
It works because it pairs two things every other tool was missing:
- **Real knowledge** — an embedded reference of 629 operators, 68 Python classes,
workflow patterns, GLSL techniques and tutorials, so the AI uses real
TouchDesigner operators instead of guessing.
- **Real execution** — a small **bridge** running inside TouchDesigner that
actually creates, connects, inspects and previews nodes — with a
create → verify → preview loop so the AI can see and fix its own work. Every
generated network is auto-arranged into a readable left→right layout.
## 📖 Documentation
Full guides and reference live on the **docs site → <https://pantani.github.io/tdmcp/>**
| For artists / musicians | For developers |
| --- | --- |
| [What is tdmcp?](https://pantani.github.io/tdmcp/guide/what-is-tdmcp) | [Architecture](https://pantani.github.io/tdmcp/reference/architecture) |
| [Install (no terminal)](https://pantani.github.io/tdmcp/guide/install) | [Tools reference](https://pantani.github.io/tdmcp/reference/tools) |
| [Your first visual](https://pantani.github.io/tdmcp/guide/first-visual) | [Environment variables](https://pantani.github.io/tdmcp/reference/environment) |
| [Shader Park](https://pantani.github.io/tdmcp/guide/shader-park) | [CLI & local copilot](https://pantani.github.io/tdmcp/reference/cli) |
| [Prompt cookbook](https://pantani.github.io/tdmcp/guide/prompt-cookbook) | [Bridge & REST API](https://pantani.github.io/tdmcp/reference/bridge-api) |
| [Recipe gallery](https://pantani.github.io/tdmcp/guide/recipes) | [Roadmap](docs/ROADMAP.md) |
| [Troubleshooting](https://pantani.github.io/tdmcp/guide/troubleshooting) | [Deployment](docs/DEPLOYMENT.md) |
🇧🇷 **Portuguese documentation:** <https://pantani.github.io/tdmcp/pt/>
## How it works
Three pieces talk to each other on your computer:
```
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. **Your AI assistant** — where you type what you want.
2. **The tdmcp server** — a small Node program that gives the AI a set of
TouchDesigner "tools" and the operator knowledge base. You install it once.
3. **The bridge** — a tiny piece that runs *inside* TouchDesigner so the server
can actually drive it. You switch it on once per machine.
## What you'll need
- **[TouchDesigner](https://derivative.ca/download)** — the free non-commercial
edition is fine.
- An MCP-capable AI assistant: **Claude Desktop** (easiest), **Claude Code**,
**Codex**, or **Cursor**.
Node.js is only needed for the build-from-source path (**[Node 20+](https://nodejs.org)**).
The one-click Claude Desktop extension needs nothing extra — the server is bundled
inside the `.mcpb` extension file.
## Get started
You set up **two sides**: your **AI** (so it gets the tdmcp tools) and
**TouchDesigner** (so the AI can drive it).
**🤖 Easiest — let your AI install it.** Using **Claude Code**, **Codex**, or
**Cursor**? Paste this one message in:
```text
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.
```
It clones, builds and wires everything up; the only manual step is pasting one
line into TouchDesigner (Step 2 below).
**🟢 Claude Desktop — one-click `.mcpb` (no terminal, no Node).** Download
**[tdmcp.mcpb](https://github.com/Pantani/tdmcp/releases/latest/download/tdmcp.mcpb)**,
then in Claude Desktop open **Settings → Extensions** and install it (drag it in or
**Install from file**). Leave host/port at `127.0.0.1` / `9980`. Full walkthrough:
[the install guide](https://pantani.github.io/tdmcp/guide/install).
**🛠️ Claude Code / Codex / Cursor — build from source.**
```bash
git clone https://github.com/Pantani/tdmcp.git
cd tdmcp
npm run setup # installs, builds, and prints the exact line to connect your client
```
### Turn on the bridge inside TouchDesigner (everyone)
**Easiest — no Textport.** Download
[**tdmcp_bridge_package.tox**](https://github.com/Pantani/tdmcp/releases/latest/download/tdmcp_bridge_package.tox)
from the latest release, drag it into your `/project1` network, and click
**Install** on the component. The package self-bootstraps and starts the bridge on
port 9980. ✅
<details>
<summary>Prefer a one-line Textport command?</summary>
Open the **Textport** (`Dialogs → Textport and DATs`), paste this **one line** and
press Enter:
```python
import urllib.request; exec(urllib.request.urlopen("https://github.com/Pantani/tdmcp/raw/v0.13.2/td/bootstrap.py").read().decode())
```
You should see `[tdmcp] bridge running on port 9980 (/project1/tdmcp_bridge)`.
</details>
Either way it's safe and reversible — it adds one tidy component; remove it later
with `from mcp import install; install.uninstall()`. Other install methods (module
path, terminal, Palette package) are in the
[bridge docs](https://pantani.github.io/tdmcp/reference/bridge-api).
### Make something
With TouchDesigner open and your AI connected, ask in plain language:
> *"Create an audio-reactive particle galaxy and show me a preview."*
The AI builds the network, checks it for errors, and returns a thumbnail. Iterate:
*"make it warmer," "add a feedback trail," "output it fullscreen."* More ideas in
the [prompt cookbook](https://pantani.github.io/tdmcp/guide/prompt-cookbook).
> **Not connecting?** The two most common fixes: make sure the bridge is on
> (`curl http://127.0.0.1:9980/api/info` returns JSON), and **restart your AI
> client** after adding the server. Full
> [troubleshooting](https://pantani.github.io/tdmcp/guide/troubleshooting).
## What you can do
**508 tools** across three layers, plus foundation primitives, CLI automation,
library/packaging, AI session memory and
Obsidian vault integrations — from one-line artist generators
(`create_feedback_network`, `create_audio_reactive`, `create_particle_system`,
`create_generative_art`, …) to building blocks (`create_control_panel`,
`animate_parameter`, `create_external_io` for OSC/MIDI/DMX/NDI, …) down to
atomic node CRUD and inspection. Many systems arrive **already playable**, with
a control panel you can tweak, preset, or map to a controller. See the full,
always-current
[tools reference](https://pantani.github.io/tdmcp/reference/tools) and the
[recipe gallery](https://pantani.github.io/tdmcp/guide/recipes).
## Optional: Creative RAG
A local, opt-in creative repertoire of open-licensed artworks/artists/techniques
the AI can search for inspiration. Off by default. Repertoire, not policy — no
bridge, DMX or Python exec. Enable with `TDMCP_RAG_ENABLED=1` plus a local
[Ollama](https://ollama.com) install, then `tdmcp creative-rag {sync|index|search}`.
Full guide: [docs/CREATIVE_RAG.md](docs/CREATIVE_RAG.md).
## Security
The bridge runs **arbitrary Python inside your TD process** and listens on port
`9980` on all interfaces — treat it like an open door to that machine. Run it only
on a trusted network, and for untrusted networks turn on bridge auth
(`TDMCP_BRIDGE_TOKEN`) and/or disable the exec endpoints
(`TDMCP_BRIDGE_ALLOW_EXEC=0`). Details:
[Security](https://pantani.github.io/tdmcp/reference/architecture#security).
## Links & community
- **Glama MCP directory** — tdmcp's listing: <https://glama.ai/mcp/servers/Pantani/tdmcp>
- **awesome-touchdesigner** — the community-curated TouchDesigner list: <https://github.com/monkeymonk/awesome-touchdesigner>
- **Docs site** — <https://pantani.github.io/tdmcp/> · **Roadmap** — [docs/ROADMAP.md](docs/ROADMAP.md)
## Contributing & development
Build with `npm install && npm run build`; run `npm test`, `npm run typecheck`,
`npm run lint`. Work on the docs with `npm run docs:dev` (the
[tools reference](https://pantani.github.io/tdmcp/reference/tools) is generated by
`scripts/gen-tool-docs.ts`). See [CONTRIBUTING.md](CONTRIBUTING.md),
[CHANGELOG.md](CHANGELOG.md), and the [roadmap](docs/ROADMAP.md).
## License
MIT — see [LICENSE](LICENSE).