@map-audio/pam-mcp-server

MCP server for the PAM audio plugin. Lets AI agents (Claude Desktop, Claude Code, Cursor, etc.) control a running PAM instance — load samples, set parameters, trigger MIDI, edit patterns, manage presets, run the randomizer, and more.

Requirements

• macOS or Windows with Node.js 21+ (node --version)
• PAM installed and running (standalone or in a DAW)
• MCP Bridge enabled inside PAM: Settings → Experimental → Beta Features → Enable MCP Bridge (default port 9847)

When PAM starts with the bridge enabled it writes ~/.pam-mcp-bridge.json — the server discovers PAM through that file, so nothing else needs configuring.

Install

Install the bridge globally once, then register the bin name pam-mcp with your MCP client. This is more reliable than npx -y for stdio MCP launchers (Claude Code in particular).

npm install -g @map-audio/pam-mcp-server

This installs a pam-mcp executable on your PATH. Verify with:

which pam-mcp
pam-mcp --version

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "pam": {
      "command": "pam-mcp"
    }
  }
}

Fully quit Claude Desktop (Cmd+Q / right-click tray icon → Quit) and reopen. PAM's tools will appear in the MCP menu.

Claude Code

claude mcp add pam pam-mcp

or add the same mcpServers block to .mcp.json at your project root.

Cursor / other MCP clients

Use the same mcpServers block in the client's MCP config. Any stdio-compatible MCP client works.

npx-based install (alternative)

npx -y @map-audio/pam-mcp-server also works in Claude Desktop and some clients, but Claude Code's stdio launcher does not resolve the npm bin shim reliably and reports "Failed to connect" even when the package is published. Prefer the global-install + bare-bin form above for Claude Code:

{
  "mcpServers": {
    "pam": {
      "command": "npx",
      "args": ["-y", "@map-audio/pam-mcp-server"]
    }
  }
}

Troubleshooting

• "Not connected to PAM plugin" — PAM isn't running, or MCP Bridge is off. Open Settings → Experimental, turn on Beta Features, then Enable MCP Bridge. The bridge starts immediately.
• "Failed to connect" / pam-mcp: command not found — the MCP client's shell PATH doesn't include the npm global bin. Run which pam-mcp in a terminal and use the absolute path it prints (e.g. /Users/you/.nvm/versions/node/v22/bin/pam-mcp) as the command value in your config. macOS GUI apps don't inherit shell PATH from ~/.zshrc/~/.bashrc, so absolute paths are the safest fallback.
• npx: command not found (if you're using the npx form) — same root cause: install Node from nodejs.org (not via nvm/asdf), or give the absolute path: "command": "/usr/local/bin/npx" / "/opt/homebrew/bin/npx".
• Offline tools fail (list_presets, get_parameter_info) — the manifest bundled with the package is used automatically. To target a different PAM install, set PAM_MANIFEST_PATH in the server's env block.

What's in the box

The main entry points:

• Read first: design_context (curated parameter cheat sheet, works offline) and get_design_overview (compact live snapshot). Prefer these over full get_state dumps or broad get_parameter_info sweeps.

• Sound design: set_parameters, update_pattern, add_modulation / add_param_seq / set_free_sequencer, update_effect_config, set_master_effects, set_drum_synth, randomize / randomize_samples / randomize_patterns.

• Generative players (PAM): list_players → set_player — arm EUCLID / KIT / TURING / WALK / MARKOV / RATCHET / PHASE / RIFF / MASK on a cell with curated presets, genre, seed, Mask/Keep and ensemble listening; 'off' restores the drawn pattern. keep_player merges the cycle playing now, the previous one, or both into the drawn pattern, or freezes it; it needs the PAM window open.

• Samples: get_default_locations → list_samples → load_sample, plus set_slices (equal / explicit / transient, with slice-to-sequence), trim/reverse/gain/normalize_sample, analyze_sample_tempo, resample_sample_to_bpm, build_sample_chain.

• Transport, MIDI & devices: start_transport / stop_transport / full_stop_transport, set_bpm, trigger_midi (+ CC / program change), midi_recording; get_audio_device_setup / set_audio_device / set_midi_io (standalone).

• Presets, variations & songs: load_preset / save_preset / new_preset, save_variation / load_variation / queue_variation, song_mode, export_song (full-track bounce), export_audio (incl. per-cell stems), export_midi (patterns as a Standard MIDI File).

• Looper: full 8-track control — arm/record/capture, load_audio_to_looper_track, warp, looper variations, live_resample.

• Plugin host (PAM builds with hosting): scan_plugins → get_plugin_scan_status → list_plugins → load_plugin → list_loaded_plugins → set_plugin_param / set_plugin_bypass.

• AI models & generation (experimental flags required): download_model / load_model / get_model_status / list_models (engines: aigen, magenta, notochord), generate_sample, generate_kit.

• Video (VX) & UI — require PAM's window to be open: get_video_state, add_video_layer, bind_video_param, video_command, …, and capture_ui (deterministic UI screenshot).

• Session takes (PAM, experimental): session_take start / stop / status — records the master WAV and the main window for pam-render.

• Offline (manifest-only): get_parameter_info, design_context, list_presets, read_preset, get_manifest_summary.

• MFX: set_mfx_routing reads and replaces the cable patch (input / sidechain → cellN → output). MFX-only; it errors on PAM and CELL1.

All three product manifests (PAM / CELL1 / MFX) are bundled; this generic server auto-selects by the connected instance's product, so one development config entry can drive all three products. Preset listing follows that product too — each has its own tree under MAP Audio. For a customer-facing MFX-only namespace, use @map-audio/mfx-mcp-server; it pins MFX discovery and removes unrelated sampler workflows from tool discovery.

Agent ergonomics

• Tool annotations. Every tool carries MCP annotations. Tools with readOnlyHint: true never change plugin state, so clients can approve them freely. destructiveHint: true marks tools that discard user state (delete_preset, reset_cell, load_preset over unsaved edits). openWorldHint is false on every tool; the server only talks to the local plugin.
• Structured output. The status tools (connection_status, select_instance, get_transport, get_manifest_summary, get_model_status, get_plugin_scan_status, workbench_sidecar_status) return structuredContent with a declared output schema, alongside the same JSON as text.
• Prompts. Five guided workflows ship as MCP prompts: build-a-beat, make-a-song, design-a-preset, mix-and-master, troubleshoot-bridge. In Claude Code they appear as slash commands (e.g. /pam:build-a-beat).
• Multiple instances. When several products run at once (say PAM and MFX), select_instance picks which one the live tools drive, matched by product name, instanceId, or port. Setting PAM_BRIDGE_PRODUCT=MFX in the server's env block pins the choice at launch. Offline parameter validation follows the selected product's manifest. Reconnection stays on the selected instance; if it disappears, select another explicitly. Repeating the same selection preserves pending commands.

Preset loading and queued operations

Server 1.24.0 adds tracked preset loading. load_preset returns a requestId and status: "queued"; poll get_preset_load_status on the same instance until it returns succeeded before editing or saving. Other outcomes are morphing, failed, cancelled, and superseded. immediate: true bypasses the native preset morph. The plugin must include the matching native bridge actions; updating the npm server alone does not add them.

Randomizer replies acknowledge queued work. Poll the affected sample paths or patterns with get_state before the next operation. Requests can coalesce, and a preset or variation load can discard pending randomization. Use randomize with target: "full" to chain samples and patterns. lfos and mods are global targets and reject cellIds.

queue_variation inherits native fade and phase settings when those options are omitted. Song Mode accepts stagger and stepped-relation fields inside transition.window on sections, connections, and song defaults; setArrangement verifies its command acknowledgment.

Preset saving

Preset saves preserve the source variation bank, including Unicode metadata. Named saves carry that bank into their destination; unnamed saves update the active user preset. Saves stop if that source is missing, unreadable, or malformed. After New / Init, give save_preset or save_variation a name before saving.

License

MIT