# Ableton Mcp Pro

> Fork of ableton-mcp adding 28 tools + an audio-listening loop (BlackHole + librosa). Lets Claude / MCP clients tune device params, mix, arrange scenes, search the Live browser, and analyze the master output for empirical mixing decisions.

- **Type:** MCP server
- **Install:** `agentstack add mcp-shaydeepalms-ableton-mcp-pro`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [shaydeepalms](https://agentstack.voostack.com/s/shaydeepalms)
- **Installs:** 0
- **Category:** [Web & Browser](https://agentstack.voostack.com/c/web-and-browser)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [shaydeepalms](https://github.com/shaydeepalms)
- **Source:** https://github.com/shaydeepalms/ableton-mcp-pro

## Install

```sh
agentstack add mcp-shaydeepalms-ableton-mcp-pro
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# ableton-mcp-pro

A fork of [ahujasid/ableton-mcp](https://github.com/ahujasid/ableton-mcp) — the Model Context Protocol bridge between Claude (and other MCP clients) and Ableton Live. This fork adds **28 additional tools** and an **audio-listening loop** that lets the LLM analyze Ableton's master output and make empirical mixing decisions.

**44 tools total** (16 upstream + 17 Phase 1 + 10 Phase 2 + 1 Phase B). Runs side-by-side with upstream on port 9878.

## What's new vs. upstream

### Phase 1 — Sound design, mixing, scenes, MIDI editing (17 tools)

- **Effects + device parameters:** `insert_native_device` (load any Ableton native device by name — Reverb, EQ Eight, Saturator, etc.), `get_device_parameters` / `set_device_parameter` (read and write any knob on any device), `delete_device`
- **Mixer:** `set_track_volume`, `set_track_pan`, `set_track_send`, `set_track_mute_solo_arm`
- **Tracks:** `create_audio_track`, `delete_track`
- **Scenes:** `create_scene`, `fire_scene`
- **Clip MIDI editing:** `get_clip_notes`, `remove_clip_notes` (the upstream could only blind-write)
- **Rack macros:** `get_rack_macros`
- **Safety:** `undo`, `redo`

### Phase 2 — Browser search, return tracks, drum pads (10 tools)

- **Browser search:** `search_browser` — find loadable presets by name across all categories (this is also how you load `.adv` presets, which the upstream couldn't do)
- **Return tracks:** `get_return_tracks`, `get_return_device_parameters`, `set_return_device_parameter`, `set_return_track_volume`, `set_return_track_pan` — tune shared sends like the default A-Reverb
- **Track grouping:** `group_tracks` (graceful fallback — `song.group_tracks` is not exposed in Live 12.1.1's Python API; tool returns a clean error pointing to manual Cmd-G)
- **Drum pads:** `get_drum_pads`, `set_drum_pad_mute_solo`
- **MIDI capture:** `capture_midi`

### Phase B — Audio-listening loop (1 tool)

**`analyze_master_output(seconds)`** — captures Ableton's master output via BlackHole, returns structured analysis:

- Integrated LUFS (ITU-R BS.1770), peak dBFS, RMS dBFS, crest factor
- Clipping check
- 7-band frequency split (sub / bass / low_mid / mid / upper_mid / presence / air) with per-band energy %
- L/R stereo correlation
- Spectral centroid (overall brightness)

The LLM can then make claims like *"your low_mid is at +6dB and the kick is clipping, drop SUB volume by 2dB and add an EQ Eight low-shelf cut at 250Hz"* — empirical decisions instead of guesses.

## Prerequisites

- **macOS** (this fork is currently macOS-only — Linux/Windows would need different audio capture + Remote Script paths)
- **Ableton Live 11+** (tested on Live 12.1.1 Suite)
- **Python 3.10+**
- **uv** — `brew install uv`
- **An MCP client** like [Claude Code](https://docs.anthropic.com/claude-code)
- **(Optional, for Phase B audio listening):** [BlackHole 16ch](https://github.com/ExistentialAudio/BlackHole) — `brew install blackhole-16ch`

## Installation

```bash
git clone https://github.com/Shaydeepalms/ableton-mcp-pro.git
cd ableton-mcp-pro
./setup.sh
```

The setup script will:

1. Create a Python venv inside the repo and install dependencies
2. Deploy the Remote Script to `~/Music/Ableton/User Library/Remote Scripts/AbletonMCPPro/`
3. Print the exact MCP config snippet you need to paste into your client's config

After running the script, three manual steps:

1. **Add the printed config snippet** to your MCP client's config — for Claude Code this is `~/.claude.json` (global) or a project-local `.mcp.json`
2. **Restart Ableton Live**, go to **Settings → Link, Tempo & MIDI**, set one of the **Control Surface** slots to **AbletonMCPPro**, with both **Input** and **Output** set to **None**
3. **Restart your MCP client** so it loads the new server

Once running, you should see `mcp__ableton-pro__*` tools available in Claude.

### Phase B — Audio listening setup (optional but recommended)

If you want Claude to *listen* to your mix:

1. **Install BlackHole:** `brew install blackhole-16ch`
2. **Open Audio MIDI Setup** (macOS Utilities) → create a **Multi-Output Device** containing both **BlackHole 16ch** and your physical output (speakers / headphones / audio interface)
3. **In Ableton: Settings → Audio → Output Device** → pick that **Multi-Output Device** (**not** BlackHole directly — that would route all audio to the virtual driver and you'd hear silence)

Now `analyze_master_output(seconds)` will capture and analyze whatever's playing in Ableton.

## Architecture

Two processes connected via TCP socket on `localhost:9878`:

```
Claude (stdio) ⇄ MCP Server (Python / FastMCP) ⇄ TCP:9878 ⇄ Remote Script (inside Ableton)
```

- **MCP Server** (`MCP_Server/server.py`) — Python, runs in your MCP client's process. Translates each tool call to a JSON command.
- **Remote Script** (`AbletonMCP_Remote_Script/__init__.py`) — Python, runs inside Ableton as a MIDI Control Surface. Listens on port 9878, dispatches commands against Live's Python API. State-mutating handlers are scheduled on Ableton's main thread.
- **Audio analyzer** (`MCP_Server/audio_analyze.py`) — captures audio from BlackHole, runs `librosa` / `pyloudnorm` analysis. Independent of the socket — direct audio capture via PortAudio.

The fork uses **port 9878** (vs. upstream's 9877), so you can run **both side-by-side** if you want to keep the upstream Ableton MCP as a fallback.

## Live API limits worth knowing

- **Automation envelopes can't be written programmatically** — `automation_state` is read-only. Workaround: a Max for Live companion device (not yet built).
- **No audio recording** from the API — would need a reverse BlackHole capture, similar to Phase B but in reverse.
- **No File → Save / Save As** — UI-only. AppleScript wrapper would work but is fragile.
- **`song.group_tracks(...)` is not exposed** in Live 12.1.1's Python API. Our `group_tracks` tool returns a clean error pointing to manual Cmd-G.
- **`.adv` preset loading DOES work** via browser URIs — use `search_browser` to find the URI, then `load_instrument_or_effect`.

## Full handbook

See [CLAUDE.md](./CLAUDE.md) for:

- All 44 tools with descriptions
- Architecture details (dual-install, port assignments, dev loop)
- Decision log (parameter-curve non-linearity, device auto-reordering, etc.)
- "How to extend" worked example (adding a new tool end-to-end)
- Real-song builds + mixing analysis (Bon Iver-style productions)

## Acknowledgments

Built on [ahujasid/ableton-mcp](https://github.com/ahujasid/ableton-mcp) by [Siddharth Ahuja](https://x.com/sidahuj). Community Discord: .

## License

MIT — see [LICENSE](./LICENSE). Original copyright Siddharth Ahuja (2025); fork additions copyright Shaydeepalms (2026).

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [shaydeepalms](https://github.com/shaydeepalms)
- **Source:** [shaydeepalms/ableton-mcp-pro](https://github.com/shaydeepalms/ableton-mcp-pro)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-shaydeepalms-ableton-mcp-pro
- Seller: https://agentstack.voostack.com/s/shaydeepalms
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.