Troubleshooting

Let's get you setup.

Quick checklist

Before diving into specific issues, verify these basics:

Node.js 18+ is installed — run node --version in Terminal
The M4L device, Talkback Bridge is on your master track and toggled on (orange indicator)
Your LLM client is open and has been restarted since you added the config
talkback-mcp appears in your client's tool list (Claude Desktop: toolbox icon; Claude Code: claude mcp list)
Port 8765 is not in use by another process — run lsof -i :8765 to check

If all five check out and things still aren't working, read on.

The device isn't connecting

Check that the MCP server is running. The Max for Live device connects to a WebSocket server on localhost:8765. If the server isn't running, the device will show a disconnected state.

Check the port. Make sure nothing else is using port 8765. You can set a different port in your MCP client config:

{
  "env": { "WS_PORT": "9000" }
}

Restart the device. Toggle the device off and on again in Ableton. This will re-initiate the WebSocket connection.

The LLM says the tool isn't available

Make sure the MCP server is properly configured in your LLM client. See the getting started guide for configuration examples.

If using Claude Desktop, verify your claude_desktop_config.json includes the talkback-mcp server entry and that you've restarted Claude Desktop after saving the config.

If using Claude Code, verify with:

claude mcp list

You should see talkback-mcp in the output.

Changes aren't being applied

Check that the device is on the master track. The Max for Live device needs to be on the master/main track to have full access to the Live Object Model.

Check the Ableton version. Talkback requires Ableton Live 11 or later with Max for Live.

Check Max console for errors. In Ableton, open the Max console (from the Max for Live device, click the wrench icon → Max Window) to see if there are any JavaScript errors.

The device caches structural data (device names, track layout, routing) and polls dynamic data (meters, mute states) on a fast interval. If you've made structural changes (added/removed tracks or devices), the cache will update on the next structure refresh cycle.

If data seems stuck, toggle the device off and on to force a fresh session scan. You can also check bridge health by asking your LLM to run get_bridge_health.

High CPU usage

The spectral analysis runs FFT processing in real-time only during a get_spectral_snapshot capture. If you're seeing consistently high CPU usage, check the bridge health metrics — large sessions with many tracks can increase poll times.

Node.js version issues

Talkback requires Node.js 18 or later. Check your version:

node --version

If you're on an older version, update via nodejs.org or your package manager of choice.

Claude Desktop picks up the wrong Node version

Symptoms: Claude Desktop shows errors like ERROR: You must supply a command or SyntaxError: Unexpected string when talkback tries to start.

Root cause: Claude Desktop does not source your shell configuration files (~/.zshrc, ~/.bashrc), so if you use nvm, fnm, or a similar Node version manager, Claude Desktop won't see your managed Node installation. It falls back to whatever node is on the system PATH — often an outdated version (e.g. v10).

Fix: Use the absolute path to your npx binary in your Claude Desktop config:

Open Terminal and run: which npx
Copy the full path (e.g. /Users/you/.nvm/versions/node/v22.12.0/bin/npx)
Update your claude_desktop_config.json

 {
   "mcpServers": {
     "talkback-mcp": {
       "command": "/Users/you/.nvm/versions/node/v22.12.0/bin/npx",
       "args": ["-y", "talkback-mcp"],
       "env": { "WS_PORT": "8765" }
     }
   }
 }

Restart Claude Desktop.

Still stuck?

Open an issue on GitHub with:

Your Ableton Live version
Your Node.js version (node --version)
Your MCP client (Claude Desktop, Claude Code, Cursor, etc.)
What you expected vs. what happened
Any error messages from the Max console or terminal