Skip to content

Configuring AI Assistants

How Phantom connects

Phantom is an MCP (Model Context Protocol) server. Your AI assistant connects to it as a tool provider, similar to how a browser connects to extensions. Once connected, Phantom’s 20 audio analysis tools appear as available functions your assistant can call.

Claude Code

The simplest setup. One command:

$ Claude Code setup

claude mcp add phantom — phantom-mcp

Verify it’s connected:

$ Verify

claude mcp list

Claude Desktop

Add Phantom to your MCP server configuration file.

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Phantom does not currently install on native Windows. WSL runs the Linux CLI; connecting a Windows desktop client to WSL requires separate client configuration.

claude_desktop_config.json

{ "mcpServers": { "phantom": { "command": "phantom-mcp", "args": [] } } }

Restart Claude Desktop after saving the file. You should see Phantom’s tools listed in the tools panel.

For assistant setup, use the MCP configuration below or the configuration guide. The Python analysis package must be installed in a supported environment.

Pro tip

If you installed Phantom in a virtual environment, use the full path to the binary: "command": "/path/to/venv/bin/phantom-mcp"

Cursor

Add to your Cursor MCP configuration (Settings > MCP Servers > Add):

Cursor MCP config

{ "mcpServers": { "phantom": { "command": "phantom-mcp", "args": [] } } }

Windsurf

For the legacy Cascade agent, add this entry to ~/.codeium/windsurf/mcp_config.json. The official Cascade MCP guide distinguishes this setup from the newer Devin Local agent, which uses its own configuration.

Windsurf MCP config

{ "mcpServers": { "phantom": { "command": "phantom-mcp", "args": [] } } }

Other MCP-compatible tools

Use an MCP client that supports launching local stdio servers. Clients limited to remote HTTP connections need a separate hosting arrangement. For local clients:

  1. Find your tool’s MCP server configuration
  2. Add an entry with "command": "phantom-mcp" and "args": []
  3. Restart the tool

Note

Phantom analyzes files on your computer. Your assistant receives file paths and measurement results and may send them to its model provider. Review that assistant’s data settings.

Connect a DAW

Phantom measures rendered audio files. A separate DAW MCP server gives your assistant access to session controls. Install both servers in the same assistant to move between measurement and session work. Available controls depend on the bridge and DAW; keep a saved session before experimenting with edits.

REAPER

Run phantom setup-reaper and follow its prompts to install the bridge, configure its startup script, and add the MCP connection. Restart REAPER and your assistant, then check the bridge connection. Use phantom setup-reaper --help for repair, dry-run, and uninstall options.

Ableton Live (Phantom 1.6.0)

Install Phantom and uv first, then run:

$ Ableton setup

phantom setup-ableton

This uses the independently maintained Ableton MCP, pinned to ableton-mcp==1.4.0. Setup runs its Remote Script installer and adds AbletonMCP and, if missing, phantom to your MCP JSON configuration. Existing unrelated servers are preserved. A conflicting AbletonMCP entry requires --force to replace.

  1. Restart Live after setup completes.
  2. In Live’s MIDI settings, choose AbletonMCP as a Control Surface.
  3. Restart your assistant and ask its Ableton MCP server to call get_session_info.
  4. Export a WAV from Live and ask Phantom to analyze its absolute path.

Successful setup means the files and configuration were installed. The get_session_info call checks that Live is actually connected.

OptionUse
--config PATHChoose the assistant’s MCP JSON file explicitly.
--scripts-dir DIRUse a custom User Library/Remote Scripts directory.
--config-onlyWrite MCP configuration without installing the Remote Script. This does not secure an existing script; restrict its listener to localhost before connecting.
--forceReplace a different existing AbletonMCP entry.
--jsonReturn setup status as JSON.

Full setup restricts the installed Remote Script listener to 127.0.0.1:9877 and stops if it cannot verify that setting. The upstream script listens on all interfaces without authentication; a localhost client setting alone does not secure it. --config-only leaves the script untouched.

The generated server configuration connects to 127.0.0.1:9877, disables upstream Ableton MCP telemetry, and disables automatic Remote Script installation when the server starts. The bridge is a separate dependency; it does not add tools to Phantom’s own tool count or provide Phantom Studio live meters.

Environment variables

Phantom reads its runtime configuration from environment variables: paths and limits, analysis thresholds, FFT/frame sizes, and behavior flags. See the Environment Variables Reference for the PHANTOM_* variables with defaults and what each one does.

Troubleshooting

“Command not found: phantom-mcp”

  • Ensure Phantom is installed: uv tool list | grep phantom-audio
  • If you installed it into a virtual environment instead, use the full path to the binary

“No tools available” after connecting

  • Restart your AI assistant after adding the configuration
  • Check the config JSON is valid (no trailing commas)
  • Verify Phantom is installed: phantom --version

Assistant can’t find audio files

  • Use absolute paths: /Users/you/Music/session/vocals.wav
  • Or relative paths from your project root if using Claude Code