TouchDesigner MCP Server: The Complete Guide (2026)

One-sentence definition

TouchDesigner MCP is an open-source Model Context Protocol server (npm: touchdesigner-mcp-server, repo 8beeeaaat/touchdesigner-mcp) that gives an AI agent a working set of hands inside a running TouchDesigner project — it can create, modify, and delete operators, inspect parameters and errors, and execute Python, driven from natural language in Claude or any other MCP client.

TouchDesigner, if you’re new to it, is a node-based visual programming environment from Derivative used for real-time visuals: projection mapping, live VJ sets, interactive installations, generative art. You build by wiring operators — small processing nodes — into a network that runs every frame. This MCP server is the bridge that lets a language model edit that network for you.

Why it exists

TouchDesigner is powerful and slow to learn. The operator catalogue runs into the hundreds, parameter names are terse, and half the real work is knowing which family of node does the thing you want. Before MCP, the loop for a beginner was: describe the idea to a chatbot, get a wall of prose, then translate that prose into clicks and wires by hand. The model never touched the project, so it never saw whether its advice actually worked.

This server closes that gap. The agent doesn’t describe a network — it builds one, reads the errors its own changes produced, and fixes them. The maintainer, who publishes under the handle 8beeeaaat, demoed the headline case early: an AI agent assembling a working particle system inside TouchDesigner, end to end, from a prompt. That clip is the clearest single statement of what changes here.

World's First! AI Agent Creates Particle System on TouchDesigner via MCP server

8-beeeaaat!!! (maintainer) on YouTube · click to play

The takeaway isn’t “AI makes the art.” It’s that the model now operates the tool, so its knowledge of TouchDesigner stops being trapped in chat and starts landing as actual operators on your canvas.

The named pieces

Four parts, and the connection only works when all four are in place. This is the mental model that makes every install step and every error message legible.

The flow is one direction of plumbing: client → MCP server (stdio) → WebServer DAT (HTTP, port 9981) → TouchDesigner. The piece people forget is #3 — the .tox is not optional, and it’s not bundled into the npm package. You install it into the project by hand, once.

Install (every client)

There are two halves to setup, and the first half is the same no matter which client you use.

Half one — the TouchDesigner side (required once): download touchdesigner-mcp-td.zip from the repo’s latest release, extract it, and import mcp_webserver_base.tox into your project (placing it at /project1/mcp_webserver_base is the recommended spot). Do not rearrange the extracted folder — the .tox loads its Python modules by relative path, so moving files breaks it. Open the Textport (Alt+T) to confirm the server started.

Half two — the client side. The install panel below pulls the exact stdio config from our catalog, so it stays in sync. The universal command is the npm package over stdio:

One-line install · TouchDesigner

Open server page

Install

Cursor

One-click install

1-Click

VS Code

One-click install

1-Click

Claude Desktop

Copy configuration

Claude Code

Copy CLI command

CLI

Gemini

Copy CLI command

CLI

Codex

Copy CLI command

CLI

Windsurf

Copy configuration

ChatGPT

Add via Settings → Connectors

M

Manual

Copy configuration

For Claude Code, the one-liner from the project’s own install guide is:

claude mcp add -s user touchdesigner -- npx -y touchdesigner-mcp-server@latest --stdio

For Claude Desktop, you can either paste the JSON config from the panel into claude_desktop_config.json, or — simplest of all — download the .mcpb bundle from the release and double-click it. Claude Desktop installs it and wires the connection for you. If TouchDesigner runs somewhere other than 127.0.0.1:9981, append --host and --port to the args. Browse config paths for every client at mcp.directory/clients (the Claude Desktop and Claude Code pages have the specifics).

A Docker image exists too, and it’s the path to an HTTP transport if you want a remote endpoint instead of a local subprocess — useful for containerized or multi-machine setups. For a single workstation, the stdio npm path is less moving parts.

The smallest end-to-end run

Once both halves are in place, the fastest way to prove the link works is to ask the agent for the server’s own status. In Claude, with TouchDesigner open:

You: Check the TouchDesigner connection and tell me what version
     is running.

Claude → get_td_info()
  ← { "build": "2023.x", "pythonVersion": "3.11", ... }

Claude: Connected. TouchDesigner is running build 2023.x on
        Python 3.11. What do you want to build?

That single round trip exercises the entire chain. If get_td_info returns, your .tox is running and the port is right. Now ask for something concrete:

You: Create a Noise TOP at /project1, then a Level TOP after it,
     and connect them.

Claude → create_td_node({ parentPath: "/project1",
                          nodeType: "noiseTOP" })
Claude → create_td_node({ parentPath: "/project1",
                          nodeType: "levelTOP" })
Claude → exec_node_method(...)   # wire op1 → op2

Claude: Done — Noise feeds a Level node at /project1. Want me to
        animate the noise transform?

Two operators appear on your canvas, wired, while you watch. This is the loop you’ll live in: ask, watch the nodes land, iterate. The exact node-type strings and return shapes depend on your TouchDesigner build — treat the snippets above as the shape of the interaction, not literal copy-paste, and let the agent resolve the current operator names via its own tools.

The 12 tools and 3 prompts

The server groups its surface into read tools, write tools, and introspection tools. Naming them is worth a minute, because it tells you exactly what the agent can and can’t reach.

Two of these carry all the risk and most of the power. The CRUD-on-nodes tools (create_td_node, update_td_node_parameters, delete_td_node) are scoped and predictable. execute_python_script is not scoped at all — it runs whatever Python the agent writes, with full project access. That last tool is why the network can be assembled so fluidly, and also why you should never point this at a project you can’t afford to lose.

The introspection cluster (get_td_classes, get_td_class_details, get_module_help) is quietly the smartest part of the design. It lets the agent look up the live TouchDesigner Python API — the same help() you’d read — so it grounds its code against your actual build instead of a remembered one. That’s the difference between code that runs and code that throws.

Alongside the tools, the server ships three guided prompts: Search node (fuzzy node lookup by name, family, or type), Node connection (instructions for wiring nodes together), and Check node errors (recursive error sweep). Prompts are reusable instruction templates the client can surface — starting points, not extra capabilities.

What I got wrong

Two assumptions cost me time, and both are common enough to be worth stating plainly.

I thought installing the npm package was the install. It isn’t. The npm package is half the system; the .tox component is the other half, and nothing in the npx command hints that you still need to import a file into TouchDesigner by hand. My first ten minutes were spent staring at ECONNREFUSEDerrors because there was nothing on port 9981 to connect to. Read the install guide’s TouchDesigner-setup section first; the npm step is meaningless without it.

I expected a prompt to produce a finished piece. “Make me an audio-reactive particle visual” produced a plausible-looking start and then a pile of half-wired operators and version mismatches. The tool is an operator-by-operator builder, not a render button. Once I switched to small, checked steps — generator, then modifier, then composite, reviewing errors at each stage — it became genuinely fast. The mental reframe is “a very quick junior operator who needs direction,” not “a magic art oracle.”

Real workflows where it earns its place

1 · Learning the operator vocabulary

This is the single best use, and it’s aimed straight at TouchDesigner’s steepest problem: knowing which node does what. Ask “what’s the right operator family for feedback trails, and build me a minimal example,” and the agent both explains and constructs. You learn by reading a working network instead of a forum post. The get_module_help tool means its answers are grounded in your actual build’s API.

2 · Scaffolding a network fast

When you know the shape you want but the wiring is tedious — twelve operators, specific parameters, a known topology — let the agent lay it down while you describe it out loud. You arrive at a working skeleton in a fraction of the click-and-drag time, then take over for the taste-level tuning that’s actually the fun part.

3 · Debugging a red node

TouchDesigner shows errors on operators but isn’t always forthcoming about why. get_td_node_errors sweeps a node and its children, hands the messages to the agent, and the agent reasons about the fix and applies it. It’s a tight loop: the model both reads the error and edits the parameter that caused it.

4 · Driving repetitive parameter edits via Python

Need the same parameter changed across forty operators, or a procedural layout generated? execute_python_script turns a tedious manual job into one instruction. This is also the tool to be most careful with — see the limits section — but for bulk, mechanical edits it’s a real time saver.

Common mistakes

Honest limits — what it can’t (and shouldn’t) do

This is the section the demo videos skip, so let’s be direct.

• It is not text-to-art. It edits a node graph; it doesn’t imagine a finished visual. The creative direction, the timing, the taste — still yours.
• execute_python_script is a loaded gun. It runs arbitrary Python with full project access. An agent that misreads your intent can delete operators or rewire things irreversibly. Work on a copy, keep the project under version control, and read tool calls before approving. This is the price of the fluency.
• TouchDesigner must be open and local. There’s no hosted mode that runs TouchDesigner for you. The agent operates your live instance; close it and everything stops.
• Operator-name accuracy depends on the build. The agent occasionally guesses a node type or parameter that doesn’t exist in your version. Its introspection tools cut this down a lot, but it isn’t zero. Expect to correct it.
• MCP resources aren’t implemented yet. The server exposes tools and prompts; the README lists resources as not implemented. So there’s no read-only, context-cheap data surface — every read goes through a tool call.

Who it’s for / who it isn’t

Community signal

The clearest endorsement is the maintainer’s own show-and-tell in r/TouchDesigner, which drew a positive reception in a subreddit that does not hand out approval freely for AI tooling.

Worth noting for honesty: this isn’t the only attempt at AI-in-TouchDesigner. A separate, commercial project called TWOZERO (from 404.zero and setupdesign) was announced as a full MCP/agent integration and got its own thread. The open-source 8beeeaaat server and a paid product can both be “TouchDesigner MCP” — if you searched the term and landed here, the one this guide covers is the free, MIT-licensed npm package. The fact that multiple teams are building this at once is itself the signal: the niche has real energy right now, and threads like “is TouchDesigner blowing up” aren’t wrong.

The verdict

Frequently asked questions

Glossary

• TouchDesigner — Derivative’s node-based environment for real-time visuals and interactive media.
• Operator (node) — a single processing unit in a TouchDesigner network. Families include TOP (textures), CHOP (channels), SOP (geometry), DAT (data), COMP (components).
• Network — the wired graph of operators that runs every frame; what you’re building.
• DAT — Data Operator. The WebServer DAT here listens for HTTP requests and is the bridge into the project.
• .tox — a saved TouchDesigner component file. mcp_webserver_base.tox is the one you import to enable MCP.
• MCP — Model Context Protocol; the standard that lets an AI client call external tools. See our explainer.
• stdio transport — the agent runs the MCP server as a local subprocess and talks over standard input/output. The default here.
• .mcpb bundle — a one-double-click installer package for Claude Desktop that wraps the whole setup.

Sources & links

Primary

• Repository & README: github.com/8beeeaaat/touchdesigner-mcp (MIT, TypeScript)
• Installation guide: docs/installation.md
• npm package: touchdesigner-mcp-server
• Maintainer demo (particle system): youtube.com/watch?v=V2znaqGU7f4

Community

• r/TouchDesigner — project announcement: “TouchDesigner MCP Server”
• r/TouchDesigner — TWOZERO (separate commercial integration): announcement thread

Internal

• TouchDesigner on MCP.Directory — catalog page, badges, live install configs
• Godot vs Unity vs Blender MCP (2026) — the adjacent creative-tooling comparison
• What is the Model Context Protocol?