<div align="center">

# Ableton MCP Extended

**Connect Ableton Live to Claude AI**

Prompt-assisted music production, end-to-end track creation, and Live session and arrangement manipulation — driven by AI. This fork adds mixer control.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Discord](https://img.shields.io/badge/Discord-join-5865F2?logo=discord&logoColor=white)](https://discord.gg/JK4hNKGprW)

[**Setup Video**](https://youtu.be/iJWJqyVuPS8) · [**Discord**](https://discord.gg/JK4hNKGprW) · [**Issues**](https://github.com/staminna/ableton-mcp-extended/issues)

</div>

---

## Quickstart

Three steps: install `uv`, point your MCP client at the server, install the Ableton Remote Script.

**1. Install uv**

```bash
# macOS
brew install uv
```

Otherwise, install from [uv's official website](https://docs.astral.sh/uv/getting-started/installation/).

> **Warning:** Do not proceed before installing uv.

**2. Add the MCP server to your client**

<details open>
<summary><b>Claude Desktop</b> — Settings → Developer → Edit Config</summary>

```json
{
    "mcpServers": {
        "AbletonMCP": {
            "command": "uvx",
            "args": [
                "ableton-mcp"
            ]
        }
    }
}
```
</details>

<details>
<summary><b>Cursor</b> — Settings → MCP</summary>

Paste this as a command:

```
uvx ableton-mcp
```
</details>

> **Warning:** Only run one instance of the MCP server (either on Cursor or Claude Desktop), not both.

**3. Install the Ableton Remote Script**

```bash
uvx --from ableton-mcp ableton-mcp-install-script
uvx --from ableton-mcp ableton-mcp-install-script --list-targets   # preview target folders first
```

**4. Connect**

1. Launch Ableton Live
2. Go to **Settings/Preferences → Link, Tempo & MIDI**
3. In the **Control Surface** dropdown, select **AbletonMCP**
4. Set **Input** and **Output** to **None**

That's it — ask Claude to build something.

---

## Table of Contents

- [Quickstart](#quickstart)
- [Features](#features)
- [Components](#components)
- [Installation](#installation)
  - [Prerequisites](#prerequisites)
  - [Claude for Desktop Integration](#claude-for-desktop-integration)
  - [Cursor Integration](#cursor-integration)
  - [Installing the Ableton Remote Script](#installing-the-ableton-remote-script)
- [Usage](#usage)
  - [Starting the Connection](#starting-the-connection)
  - [Using with Claude](#using-with-claude)
  - [Capabilities](#capabilities)
  - [Example Commands](#example-commands)
- [Troubleshooting](#troubleshooting)
- [Technical Details](#technical-details)
- [Limitations & Security Considerations](#limitations--security-considerations)
- [Telemetry](#telemetry)
- [Join the Community](#join-the-community)
- [Contributing](#contributing)
- [Disclaimer](#disclaimer)

---

## About this fork

A fork of [ahujasid/ableton-mcp](https://github.com/ahujasid/ableton-mcp) by
[Siddharth Ahuja](https://x.com/sidahuj), MIT licensed, tracking upstream
**1.3.8** and adding mixer control — see [Mixer control](#mixer-control).

**Why:** you can ask the upstream MCP to build an arrangement, but not to balance
it. Mixer levels are readable but not writable — `get_track_info` returns
`mixer_device.volume.value`, yet nothing can set it, because
`set_device_parameter` resolves through `track.devices[...]` and the mixer is not
a device. Panning and sends are in the same position. This fork adds `get_mixer`,
`set_track_volume`, `set_track_panning` and `set_send`, addressing levels in
**real decibels** rather than raw fader position.

The mixer work is upstreamed as
[ahujasid/ableton-mcp#122](https://github.com/ahujasid/ableton-mcp/pull/122); if
it lands, this fork has no reason to exist. Everything else here — including the
telemetry and dataset consent flow — is upstream's, unchanged. Set
`DISABLE_TELEMETRY=true` in the server's `env` to opt out.

---

## Features

| | |
|---|---|
| **Two-way communication** | Connect Claude AI to Ableton Live through a socket-based server |
| **Track manipulation** | Create, modify, and manipulate MIDI and audio tracks |
| **Instrument and effect selection** | Claude can access and load the right instruments, effects and sounds from Ableton's library |
| **Clip creation** | Create and edit MIDI clips with notes |
| **Arrangement view composition** | Build full songs autonomously in Arrangement View, including sections like intro, buildup, drop, breakdown, and outro |
| **Session control** | Start and stop playback, fire clips, and control transport across Session View and Arrangement View |
| **Anonymous telemetry** | Usage tracking to help improve the tool (can be disabled) |

## Components

The system consists of two main components:

1. **Ableton Remote Script** (`Ableton_Remote_Script/__init__.py`) — a MIDI Remote Script for Ableton Live that creates a socket server to receive and execute commands
2. **MCP Server** (`server.py`) — a Python server that implements the Model Context Protocol and connects to the Ableton Remote Script

---

## Installation

### Prerequisites

- **Ableton Live** 10 or newer
- **Python** 3.8 or newer
- **uv** package manager

If you're on Mac, please install uv as:

```
brew install uv
```

Otherwise, install from [uv's official website](https://docs.astral.sh/uv/getting-started/installation/)

> **Warning:** Do not proceed before installing uv.

### Claude for Desktop Integration

[Follow along with the setup instructions video](https://youtu.be/iJWJqyVuPS8)

Go to **Claude → Settings → Developer → Edit Config → `claude_desktop_config.json`** to include the following:

```json
{
    "mcpServers": {
        "AbletonMCP": {
            "command": "uvx",
            "args": [
                "ableton-mcp"
            ]
        }
    }
}
```

### Cursor Integration

Run ableton-mcp without installing it permanently through uvx. Go to **Cursor Settings → MCP** and paste this as a command:

```
uvx ableton-mcp
```

> **Warning:** Only run one instance of the MCP server (either on Cursor or Claude Desktop), not both.

### Claude Code Integration

In the terminal, run:

```
claude mcp add AbletonMCP uvx ableton-mcp
```

### Installing the Ableton Remote Script

[Follow along with the setup instructions video](https://youtu.be/iJWJqyVuPS8)

Install the Remote Script with:

```bash
uvx --from ableton-mcp ableton-mcp-install-script
uvx --from ableton-mcp ableton-mcp-install-script --list-targets   # preview target folders first
```

> If you installed the package with `pip` or `pipx`, the command is on your PATH directly — just run `ableton-mcp-install-script`.

This copies the matching Remote Script into Ableton's **User Remote Scripts** folder. If a different version of the script is already there, the existing file is backed up to `__init__.py.bak` before being replaced.

Then **restart Ableton** (or re-select the AbletonMCP control surface) so Live loads it. Re-run the command after upgrading the package — the server logs a warning when the loaded script version doesn't match what it expects.

> **Note:** The server does **not** install the script on startup. Writing into Ableton's preferences directory is an explicit action, not a side effect of launching a server.

**First-time Ableton setup:**

1. Run `uvx --from ableton-mcp ableton-mcp-install-script`
2. Launch Ableton Live
3. Go to **Settings/Preferences → Link, Tempo & MIDI**
4. In the **Control Surface** dropdown, select **AbletonMCP**
5. Set **Input** and **Output** to **None**

<details>
<summary><b>Manual fallback locations (User Remote Scripts)</b></summary>

- **macOS:** `/Users/[Username]/Library/Preferences/Ableton/Live XX/User Remote Scripts/AbletonMCP/`
- **Windows:** `C:\Users\[Username]\AppData\Roaming\Ableton\Live x.x.x\Preferences\User Remote Scripts\AbletonMCP\`
</details>

The MCP server and Remote Script share a version handshake (`get_remote_script_info`). If they diverge, newer tools degrade gracefully until Live is restarted.

---

## Usage

### Starting the Connection

1. Ensure the Ableton Remote Script is loaded in Ableton Live
2. Make sure the MCP server is configured in Claude Desktop or Cursor
3. The connection should be established automatically when you interact with Claude

### Using with Claude

Once the config file has been set on Claude, and the remote script is running in Ableton, you will see a hammer icon with tools for the Ableton MCP.

### Capabilities

- Get session and track information
- Create and modify MIDI and audio tracks
- Create full song arrangements from start to finish in Arrangement View
- Create, edit, and trigger clips
- Control playback
- Load instruments and effects from Ableton's browser
- Add notes to MIDI clips
- Change tempo and other session parameters
- Read and set mixer levels — volume, panning and sends
- Mute, solo and arm tracks
- Measure levels and gain-stage per track or group to a master target
- Measure real loudness (LUFS and true peak) and balance tracks against it

### Mixer control

`get_mixer`, `set_track_volume`, `set_track_panning` and `set_send` work on
regular tracks, return tracks and the master (`track_type` is `"track"`,
`"return"` or `"master"`).

Levels are set in decibels:

```
set_track_volume(track_index=0, db=-4)
set_send(track_index=0, send_index=0, db=-12)
```

Prefer `db` over the raw `value`. Live's fader position is not proportional to
level — 0.85 is 0 dB and 1.0 is +6 dB — and the taper has no published closed
form, so approximating it drifts away from unity gain. Passing `db` resolves the
exact fader position by bisecting against `DeviceParameter.str_for_value()`,
i.e. asking Live what a position actually reads as. Accuracy is bounded by
Live's own 0.01 dB display resolution. Targets beyond the fader range clamp to
its ends.

`get_mixer` reports each parameter three ways — the raw value, the dB, and the
string Live displays:

```json
{
  "name": "1-Drums",
  "volume": { "value": 0.85, "db": 0.0, "display": "0.0 dB" },
  "panning": { "value": 0.0, "db": null, "display": "C" },
  "sends": [ { "index": 0, "name": "A Reverb", "db": -12.0, "display": "-12.0 dB" } ]
}
```

### Headroom and push

Three tools turn measured levels into gain moves, so you can ask for a mix that
hits a target instead of nudging faders by hand.

```
measure_mix(start_beats=0, length_beats=16)
set_master_headroom(target_db=-6)
push_track(track_index=2, db=3)
```

`measure_mix` plays a stretch of the Arrangement, samples every track, group,
return and the master, then restores the playhead and play state. Omit
`start_beats` to measure whatever is already playing, which is how to read
Session-view clips — the transport has to be running in that case.

`set_master_headroom` gain-stages the whole mix to a master peak target.
`scope="tracks"` (the default) moves every top-level track and group by the same
amount, so the balance of the mix is untouched and the master fader stays where
it is; `scope="master"` moves only the master fader instead. **Group children
are deliberately left alone** — their group fader already carries them, so
trimming both would apply the change twice.

**It only turns things down.** Sampling meters at ~10 Hz can miss a peak but
never invent one, so a measured level is a *floor* on the real one: trimming to
a target lands at or below it, while boosting to a target can clip on the
transients the sampling never saw. A mix already under the target is reported
and left alone. `allow_boost=True` overrides that — expect to want a limiter.

`push_track` brings one track or group forward: `db` for a relative move, or
`to_peak_db` to land its own measured peak on a level. Pointed at a group it
moves the whole group together. With `keep_headroom` it re-measures afterwards
and trims the master back to the ceiling, which keeps every relative balance
including the push you just made.

Each tool measures, moves, and then measures again, reporting what actually
landed rather than what it predicted. Five things are worth knowing about the
numbers, all of them measured on Live 12.4.3 rather than assumed:

- **Peak, not loudness.** Live's API exposes meters, not LUFS, so every target
  is peak dBFS. There is no loudness reading to aim at.
- **~10 Hz sampling.** Meters can only be read on Live's main thread, so
  transients shorter than a tick can be missed. Each result reports its sample
  count. This is gain staging, not true-peak compliance — keep a limiter for
  that.
- **The meter scale is linear in decibels**, spanning ~74 dB across its 0..1
  range with 1.0 at 0 dBFS. That was established by moving a fader in exact
  steps — Live states the dB itself — and fitting the meter's response over a
  40 dB sweep; it recovers known moves to within about 1 dB. It is *not* the
  volume fader's taper, and it is not linear amplitude; assuming either gets
  the level wrong by roughly a factor of two.
- **Peak readings repeat to about 2 dB.** Five reads of an unchanged mix
  spanned 2.04 dB (0.72 dB stdev), which is why the default tolerance is 2 dB:
  the tools stop once the master is inside the noise floor of its own
  measurement instead of moving faders to chase a reading. Measure over more
  beats if you want a steadier peak. `set_master_headroom` also learns from
  each pass — if a fader move of X dB doesn't shift the master by X, the next
  correction is scaled by the response actually observed.
- **Silence is refused,** rather than treated as a level to push up, and a
  track whose output is MIDI is reported as having no meter rather than as a
  silent audio track.

### Real loudness: LUFS and true peak

Everything above reads Live's peak meters. These four tools measure the audio
itself, which is what balancing actually needs — peak says nothing about how
loud something *sounds*.

```
measure_master_loudness(start_beats=0, length_beats=16)
set_master_loudness(target_lufs=-14)
measure_track_loudness()
balance_tracks(targets={"0": -12.0, "1": -18.0})
```

Live's API exposes no loudness reading, so the audio is captured from a
loopback device and scanned with ffmpeg's `ebur128` — proper ITU-R BS.1770:
gated integrated LUFS, loudness range, and **true peak**.

**Setup (one-time).** You need [ffmpeg](https://ffmpeg.org) and
[BlackHole](https://existential.audio/blackhole), then a copy of Live's output
going to BlackHole: in **Audio MIDI Setup**, create or open a **Multi-Output
Device**, tick both your speakers and **BlackHole 2ch** (speakers as clock
master, drift correction on BlackHole), and select that device in Live's
**Preferences → Audio**. You keep hearing everything; BlackHole just carries a
copy. Without it the tools say so, and say which of the two possible causes it
is — they check Live's own meters to tell "not routed" apart from "nothing is
playing".

`set_master_loudness` is the tool for "get me to −14 LUFS for streaming".
Loudness scales exactly with gain — add 3 dB and the reading rises 3.0 — so one
move lands it, unlike the peak-meter tools which can only iterate. **Turning up
is safe here**, because a real true-peak figure exists: if the move would push
true peak past `ceiling_dbtp` (−1 dBTP by default), it is capped there and the
result says so.

`measure_track_loudness` solos each track in turn, measures it, and puts every
solo back exactly as it was. `balance_tracks` then moves each fader to the
target you give it and restores the master loudness afterwards. It executes a
balance; it does not invent one — measure first, then decide the numbers.

Two costs to know: measuring needs **real-time playback**, so a per-track pass
over eight tracks at 16 beats and 120 BPM is about 80 seconds of your mix
soloing past, and the capture picks up **anything else routed to BlackHole**, so
quit other audio apps before trusting a reading.

### Example Commands

Here are some examples of what you can ask Claude to do:

| Prompt | Demo |
|---|---|
| *"Create an 80s synthwave track"* | [Watch](https://youtu.be/VH9g66e42XA) |
| *"Create a Metro Boomin style hip-hop beat"* | |
| *"Create a full arrangement with an intro, buildup, drop, breakdown, and outro"* | |
| *"Create a new MIDI track with a synth bass instrument"* | |
| *"Add reverb to my drums"* | |
| *"Create a 4-bar MIDI clip with a simple melody"* | |
| *"Get information about the current Ableton session"* | |
| *"Load a 808 drum rack into the selected track"* | |
| *"Add a jazz chord progression to the clip in track 1"* | |
| *"Set the tempo to 120 BPM"* | |
| *"Play the clip in track 2"* | |
| *"Set every track to -4 dB"* | |
| *"Pan the hats 30% left and send them to the reverb at -12 dB"* | |
| *"Measure bars 1-8 and tell me what's eating the headroom"* | |
| *"Gain-stage the mix so the master peaks at -6 dB"* | |
| *"Push the drum group 3 dB without breaking the ceiling"* | |
| *"How loud is this master in LUFS?"* | |
| *"Get the master to -14 LUFS for streaming"* | |
| *"Measure each track and put the bass 6 LU under the drums"* | |

---

## Troubleshooting

| Problem | Fix |
|---|---|
| **Connection issues** | Make sure the Ableton Remote Script is loaded, and the MCP server is configured on Claude |
| **Timeout errors** | Try simplifying your requests or breaking them into smaller steps |
| **Have you tried turning it off and on again?** | If you're still having connection errors, try restarting both Claude and Ableton Live |

## Technical Details

### Communication Protocol

The system uses a simple JSON-based protocol over TCP sockets:

- **Commands** are sent as JSON objects with a `type` and optional `params`
- **Responses** are JSON objects with a `status` and `result` or `message`

## Limitations & Security Considerations

- Creating complex musical arrangements might need to be broken down into smaller steps
- The tool is designed to work with Ableton's default devices and browser items
- Always save your work before extensive experimentation

---

## Telemetry

AbletonMCP collects usage data to help improve the tool. This includes:

- Anonymous tool usage statistics (which features are used)
- Anonymous session start information (for daily/monthly active user counts)
- Anonymous rates and performance metrics
- Prompts, MIDI notes, track and clip names, and device settings

Telemetry is **on** by default. To see exactly what data is collected, see the [Terms & Data Use](TERMS.md).

### Opting Out

To disable telemetry, set one of these environment variables before starting the MCP server:

```bash
export ABLETON_MCP_DISABLE_TELEMETRY=true
```

Or use any of these alternatives:

- `DISABLE_TELEMETRY=true`
- `MCP_DISABLE_TELEMETRY=true`

For Claude Desktop, add the environment variable to your config:

```json
{
    "mcpServers": {
        "AbletonMCP": {
            "command": "uvx",
            "args": ["ableton-mcp"],
            "env": {
                "ABLETON_MCP_DISABLE_TELEMETRY": "true"
            }
        }
    }
}
```

---

## Join the Community

Give feedback, get inspired, and build on top of the MCP: [**Discord**](https://discord.gg/JK4hNKGprW)

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Disclaimer

This is a third-party integration and not made by Ableton. Made by [Siddharth](https://x.com/sidahuj).

---

<div align="center">

**If Ableton MCP is useful to you, consider starring the repo**

</div>