MCP server for TouchDesigner — build, wire, and debug networks with AI. Plus git-diffable externalization.
# Add to your Claude Code skills
git clone https://github.com/dylanroscover/EmbodyGuides for using mcp servers skills like Embody.
Create at the speed of thought.
Full Documentation | Manifesto | Changelog
Embody puts your ideas on screen as fast as you can describe them. Operators, connections, parameters, the works. Want to try a different direction? Spin up a new approach in seconds. Compare attempts side by side. Branch off the one that works. The tool keeps up with you, instead of the other way around.
Envoy — forward velocity. An embedded MCP server lets Claude Code, Cursor, and Windsurf talk directly to your live TouchDesigner session. Create operators, wire them up, set parameters, write extensions, debug errors — by saying what you want. No copy-pasting code. No describing your network in chat. Idea → operators in seconds.
Embody — lateral velocity. Tag any operator and Embody externalizes it to files on disk that mirror your network hierarchy. Try a new direction, branch off a good one, restore the state from yesterday — all in seconds. Your externalized files are the source of truth, so every project opens already in flow.
No comments yet. Be the first to share your thoughts!
Top skills in this category by stars
TDN — the substrate that makes both possible. TouchDesigner networks exported as human-readable JSON. The format is what lets your AI agent understand what's on the screen, what lets you diff one attempt against another, and what lets a network reconstruct itself from text on the next project open. TDN is what makes the rest of this possible.

| | What | Why it matters |
|---|---|---|
| 🤖 | Envoy MCP Server | 47 tools let your AI assistant build, wire, parameterize, and debug live networks. The first time you watch it happen, you stop typing operator names by hand for good. |
| 📄 | TDN Network Format | Networks become text. Diff two versions, revisit any version, hand an LLM a complete picture of what's on screen — all from a single .tdn file. |
| 📦 | Automatic Restoration | Externalized operators rebuild themselves from disk on every project open. The .toe is no longer the source of truth — your files are. |
| 📤 | Portable Tox Export | Pull any COMP out as a self-contained .tox with external references stripped. Ship a piece of your project anywhere. |
Embody writes externalized files relative to your .toe location — no special folder structure required. Embody works in any project folder; if you happen to use git, every change is also a clean diff for free.
my-project/ ← project folder (optionally a git repo)
├── my-project.toe ← your TouchDesigner project
├── base1/ ← externalized operators
│ ├── base2.tox ← COMP (TOX strategy)
│ ├── base3.tdn ← COMP (TDN strategy — diffable JSON)
│ └── text1.py ← DAT
└── ...
.tox from /release and drag it into your TouchDesigner projectlctrl twice to tag and externalize itctrl + shift + u to update all externalizations, or ctrl + alt + u to update only the current COMP. On project open, Embody restores everything from disk automaticallyTip: If no operators are tagged, Embody will externalize all eligible COMPs and DATs, which may slow down complex projects. Tagging selectively is recommended.
| Shortcut | Action |
|----------|--------|
| lctrl + lctrl | Tag or manage the operator under the cursor |
| ctrl + shift + u | Update all externalizations |
| ctrl + alt + u | Update only the current COMP |
| ctrl + shift + r | Refresh tracking state |
| ctrl + shift + o | Open the Manager UI |
| ctrl + shift + e | Export entire project to .tdn file |
| ctrl + alt + e | Export current COMP to .tdn file |
For supported formats, folder configuration, duplicate handling, Manager UI, and more — see the Embody docs.
Embody includes Envoy, an embedded MCP server that gives AI coding assistants direct access to your live TouchDesigner session.
Envoyenable parameter on the Embody COMPlocalhost:9870 (configurable via Envoyport).mcp.json in your git repo root.mcp.json automaticallyIf your project isn't in a git repo, add .mcp.json manually to your project root:
{
"mcpServers": {
"envoy": {
"type": "http",
"url": "http://localhost:9870/mcp"
}
}
}
| Tool | What It Does |
|------|-------------|
| create_op | Create any operator type in any network |
| set_parameter | Set values, expressions, or bind modes on any parameter |
| connect_ops | Wire operators together |
| execute_python | Run arbitrary Python in TD's main thread |
| export_network | Export networks to diffable .tdn JSON |
| create_extension | Scaffold a full extension (COMP + DAT + wiring) |
| get_op_errors | Inspect errors on any operator and its children |
...and 37 more. See the full tools reference.
When Envoy starts, it generates a CLAUDE.md file in your project root with TD development patterns, the complete MCP tool reference, and project-specific guidance.
TDN (TouchDesigner Network) is the file format that makes the rest of Embody possible. It exports an entire operator network — operators, connections, parameters, layout, annotations, DAT content — as a single human-readable JSON file. Your AI agent can read it. You can read it. Any text tool can diff it. The network can rebuild itself from it on the next project open.
This is the substrate. Every other capability — AI-driven building, version control, automatic restoration — builds on top of it.
ctrl + shift + ectrl + alt + eexport_network / import_network MCP toolsSee the full TDN specification for format details, import process, and round-trip guarantees.
Embody provides a multi-destination logging system:
dev/logs/<project_name>_YYMMDD.log, auto-rotates at 10 MBPrint parameter to echo logsget_logs MCP toolop.Embody.Log('Something happened', 'INFO')
op.Embody.Warn('Check this out')
op.Embody.Error('Something broke')
Embody includes 49 test suites covering core externalization, MCP tools, TDN format, and server lifecycle. Tests run inside TouchDesigner using a custom test runner with sandbox isolation.
op.unit_tests.RunTests() # All tests (non-blocking)
op.unit_tests.RunTests(suite_name='test_path_utils') # Single suite
op.unit_tests.RunTestsSync() # All in one frame (blocks TD)
Via Envoy MCP: use the run_tests tool. See the full testing docs for coverage details and how to write new tests.
For more, see Troubleshooting.
See the full changelog for detailed version history.
Recent releases:
EmbodyExt.Update() rename-detection used self.ownerComp (an EnvoyExt-only attribute) instead of self.my. Every Update tick during a save threw AttributeError, which got caught and logged at WARNING but meant the rename-detect path never actually fired. Layer 2 walk-forward in the bridge masked the symptom (lookups still resolved correctly), but the registry would have stayed perpetually keyed to the previous version. One-character fix._writeEnvoyConfig now garbage-collects dead-PID rows on every write — registries that previously accumulated dead entries across sessions (hard kills, force-quits, crashes) collapse to live-only on the next save (verified: 28 rows → 1 in one cycle). EmbodyExt.Update() caches _last_toe_name and triggers RefreshRegistry() on basename mismatch — defensive backstop for execute.py's postSave hook in case it didn't reload. Bridge handle_launch_td adds a PID-aware slow-path scan after the fast-path key