tdmcp

English

Português

English

Português

Appearance

Troubleshooting ​

Most problems are one of a handful of things. Find what you're seeing below.

"TouchDesigner isn't reachable" ​

The AI can't find the bridge. Check, in order:

  1. Is TouchDesigner open? It needs to be running.
  2. Did you turn on the bridge? In TouchDesigner's Textport you should have seen [tdmcp] bridge running on port 9980. If not, redo step 3 of the install.
  3. Quick test: open a terminal and run curl http://127.0.0.1:9980/api/info — it should return some JSON. If it does, the bridge is fine and the issue is on the AI-client side (next item).

The AI doesn't list any tdmcp tools ​

The client didn't load the server.

  • Restart your AI client after installing/enabling the extension. This is the most common fix — the tools only appear after a restart.
  • On Claude Desktop, confirm the "TouchDesigner (tdmcp)" extension is enabled in Settings → Extensions.

The local copilot says "LLM offline" ​

tdmcp chat talks to a local LLM (Ollama by default). If the header shows LLM offline or messages fail with fetch failed:

  1. Restart tdmcp chat (Ctrl-C, run it again). It auto-starts Ollama for you — so a fresh launch brings the daemon back up if it had stopped.
  2. Is Ollama installed? It must be on your PATH — get it at ollama.com. (Homebrew's Ollama isn't a persistent daemon and can stop between sessions; tdmcp chat starting it for you covers that.)
  3. Model not pulled? If the status says model not pulled, click Pull in the UI or run ollama pull qwen2.5:3b.
  4. Started with --no-ollama? Then start the daemon yourself: ollama serve.
  5. Using a remote / cloud endpoint? Check TDMCP_LLM_BASE_URL and TDMCP_LLM_API_KEY in your environment.

macOS microphone & camera permission ​

The first time a visual uses your microphone (audio-reactive) or camera (webcam), macOS shows a permission dialog.

  • Click Allow. Until you respond, TouchDesigner can look frozen (it's waiting on the popup, sometimes with high CPU). That's expected — it isn't a crash.
  • If you accidentally clicked Deny, fix it in System Settings → Privacy & Security → Microphone (or Camera), enable TouchDesigner, and restart it.
  • Don't want the popup while testing? Ask for a test tone source instead of the microphone: "use a test oscillator instead of the mic."

The download / Textport line shows a network error ​

Both the .mcpb download and the one-line bridge installer need to reach the internet (GitHub).

  • Reconnect to the internet and try again.
  • Download link 404s? A release may not be published yet — ask whoever shared tdmcp for the tdmcp.mcpb file directly and install from the file.

"Port 9980 is already taken" ​

Something else is using that port. Use a different one in both places:

  • In TouchDesigner: from mcp import install; install.run(port=9981)
  • In your AI client's settings: set the TouchDesigner port to 9981 (or the TDMCP_TD_PORT environment variable).

A visual built, but looks off ​

The audio / particle / 3D builders and the more exotic recipes use best-effort parameter names and may need a nudge. Just say what's wrong:

  • "The particles aren't moving — check it for errors and fix them."
  • "Explain what this network does so I can see what's missing."

It runs slowly ​

"This is running slow — find the bottleneck and lower the resolution where it won't hurt."

The AI can measure cook times and optimize the heaviest parts.

TDAbleton Mapper is not moving Ableton ​

For the MediaPipe hands to Auto Filter flow, AbletonMCP is not part of the runtime path. The path is TouchDesigner MediaPipe hands -> TDAbleton TDA_Mapper -> Ableton mapped parameter.

Check, in order:

  1. TouchDesigner is playing; MediaPipe capture does not update while the timeline is paused.
  2. The hand adapter CHOP has non-zero confidence and handedness.
  3. /project1/hand_ableton_mapper/mapper_send has moving map1, map2, map3, and map4 channels.
  4. Left hand moves map1/map3; right hand moves map2/map4.
  5. The active TDA_Mapper path is the real track/device target, not a stale mapper from another track.
  6. Oscinputchop points at mapper_send, Reorder is map1 map2 map3 map4, Bypass1..4 are off, and Min/Max1..4 are 0..1.
  7. The four TDAbleton mapper slots are manually mapped to Auto Filter or rack macro parameters in Ableton.

Run diagnose_tdableton_mapper to inspect the mapper state from TouchDesigner and use repair:true only when you want tdmcp to restore the input CHOP, reorder, bypass, and range parameters.

Still stuck? ​

Open an issue at github.com/Pantani/tdmcp/issues. Developers: the reference docs cover deeper diagnostics.