Metadata-Version: 2.4
Name: ableton-mcp-full
Version: 2.0.0
Summary: Full-coverage Ableton Live integration through the Model Context Protocol (mixer, automation, devices, scenes, arrangement, and more)
Author-email: Moody <info@moodyprogramming.de>
License: MIT
Project-URL: Homepage, https://github.com/jhurliman/ableton-mcp
Project-URL: Bug Tracker, https://github.com/jhurliman/ableton-mcp/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp[cli]>=1.3.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Dynamic: license-file

# AbletonMCP - Ableton Live Model Context Protocol Integration

AbletonMCP connects Ableton Live to Claude AI through the Model Context Protocol (MCP), allowing Claude to directly interact with and control Ableton Live. This integration enables prompt-assisted music production, track creation, and Live session manipulation.

### Join the Community

Give feedback, get inspired, and build on top of the MCP: [Discord](https://discord.gg/3ZrMyGKnaU). Made by [Siddharth](https://x.com/sidahuj)

## Features

- **Two-way communication**: Connect Claude AI to Ableton Live through a socket-based server
- **Full track control**: Create, delete, duplicate, rename, color, mute/solo/arm, route, and fold MIDI, audio, and return tracks
- **Mixer control**: Volume, panning, sends, crossfader assignment, and the master track
- **Session and arrangement clips**: Create, delete, duplicate, quantize, loop, and read/write MIDI notes; duplicate clips into the arrangement
- **Scenes**: Create, delete, duplicate, fire, rename, color, and tempo-lock scenes
- **Devices**: Load instruments/effects/samples from the browser, toggle devices, and read/write any device parameter, including inside racks and drum pads
- **Automation**: Insert and clear clip envelope automation for device parameters
- **Transport**: Play/stop/continue, loop region, punch in/out, overdub, session record, and cue points
- **Session introspection**: Full session/track/clip/scene/device state as structured JSON

## Components

The system consists of two main components, each organized by domain rather than as one large file:

1. **Ableton Remote Script** (`AbletonMCP_Remote_Script/`): A MIDI Remote Script for Ableton Live that opens a JSON/TCP socket server and dispatches commands to handler modules that call the Live Object Model (LOM).
   - `socket_server.py` - generic threaded JSON-over-TCP server (no Live API dependency)
   - `dispatcher.py` - command registry and dispatch, with a `LiveContext` indirection layer
   - `live_api_utils.py` - pure helpers for looking up and serializing Live objects
   - `handlers/` - one module per domain: `session`, `transport`, `tracks`, `mixer`, `clips`, `scenes`, `devices`, `automation`, `browser`, `application`
   - `__init__.py` - thin `ControlSurface` subclass that wires the socket server to the dispatcher
2. **MCP Server** (`MCP_Server/`): A Python server that implements the Model Context Protocol and connects to the Ableton Remote Script.
   - `connection.py` - the TCP/JSON client (`AbletonConnection`)
   - `mcp_instance.py` - the shared `FastMCP` instance and lifespan
   - `tools/` - one module per domain, mirroring the Remote Script's handler modules 1:1
   - `server.py` - thin entry point that registers all tools and runs the server

Everything except the `ControlSurface` subclass itself (which needs Live's `_Framework`) is plain, dependency-free Python, importable and unit-testable outside of Ableton Live.

## Installation

### Prerequisites

- Ableton Live 10 or newer
- Python 3.8 or newer
- [uv package manager](https://astral.sh/uv)

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/]

⚠️ Do not proceed before installing UV

### Claude for Desktop Integration

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

1. Go to Claude > Settings > Developer > Edit Config > claude_desktop_config.json to include the following:

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

### Cursor Integration

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

```
uvx ableton-mcp-full
```

⚠️ Only run one instance of the MCP server (either on Cursor or Claude Desktop), not both

### Installing the Ableton Remote Script

[Follow along with the setup instructions video](https://youtu.be/iJWJqyVuPS8) (note: the video shows the older single-file version; the install location is the same, but you now copy a folder of files instead of a single `__init__.py`)

1. Download this repo, or at minimum the whole `AbletonMCP_Remote_Script/` directory (it now contains several files and a `handlers/` subfolder, not just `__init__.py`)

2. Find Ableton's MIDI Remote Scripts directory. Different OS and versions have different locations. **One of these should work, you might have to look**:

   **For macOS:**
   - Method 1: Go to Applications > Right-click on Ableton Live app → Show Package Contents → Navigate to:
     `Contents/App-Resources/MIDI Remote Scripts/`
   - Method 2: If it's not there in the first method, use the direct path (replace XX with your version number):
     `/Users/[Username]/Library/Preferences/Ableton/Live XX/User Remote Scripts`

   **For Windows:**
   - Method 1:
     C:\Users\[Username]\AppData\Roaming\Ableton\Live x.x.x\Preferences\User Remote Scripts
   - Method 2:
     `C:\ProgramData\Ableton\Live XX\Resources\MIDI Remote Scripts\`
   - Method 3:
     `C:\Program Files\Ableton\Live XX\Resources\MIDI Remote Scripts\`
   *Note: Replace XX with your Ableton version number (e.g., 10, 11, 12)*

3. Create a folder called `AbletonMCP` in the Remote Scripts directory and copy the **entire contents** of this repo's `AbletonMCP_Remote_Script/` directory into it (`__init__.py`, `dispatcher.py`, `socket_server.py`, `live_api_utils.py`, and the `handlers/` subfolder) -- so you end up with `.../AbletonMCP/__init__.py`, `.../AbletonMCP/handlers/tracks.py`, etc.

4. Launch (or restart) Ableton Live

5. Go to Settings/Preferences → Link, Tempo & MIDI

6. In the Control Surface dropdown, select "AbletonMCP"

7. Set Input and Output to "None"

## 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

Every tool below is available both to Claude (as an MCP tool) and as a Remote Script command; the two are always kept in exact 1:1 correspondence (enforced by a test, see [Testing](#testing)).

**Session & transport** - tempo, time signature, metronome, clip trigger quantization, undo/redo, play/stop/continue, song position, loop region, punch in/out, overdub, session record, cue points

**Tracks & mixer** - create/delete/duplicate MIDI, audio, and return tracks; rename, color, mute/solo/arm, monitoring state, input/output routing, group track fold state; volume, panning, sends, crossfader assign, master volume/crossfader

**Clips** - create/delete/duplicate session clips; fire/stop clips and stop-all; rename, color, loop region, quantize; add/get/remove MIDI notes; duplicate a session clip into the arrangement and list/delete arrangement clips

**Scenes** - create/delete/duplicate/fire scenes; rename, color, and tempo-lock

**Devices** - list devices on a track; load instruments/effects/samples from the browser; delete/activate devices; list/get/set device parameters; inspect rack chains and drum pads

**Automation** - clear and insert clip envelope points for any device parameter

**Browser** - browse the full category tree, look up items by path or URI, load items onto tracks, and preview items before loading

## Example Commands

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

- "Create an 80s synthwave track" [Demo](https://youtu.be/VH9g66e42XA)
- "Create a Metro Boomin style hip-hop beat"
- "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"
- "Automate the filter cutoff on the bass to sweep up over 4 bars"
- "Set up a group track with a compressor on the return"
- "Duplicate this clip into the arrangement at bar 9"


## Troubleshooting

- **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
- **"Unknown command" errors**: The Remote Script folder in Ableton's Remote Scripts directory is out of date -- re-copy the full `AbletonMCP_Remote_Script/` directory (see Installation) and restart Live
- **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`
- All Live API access happens on Ableton's main thread; the Remote Script hops there internally and blocks the socket response until the command completes, so the client never has to guess when it's safe to send the next command

### Testing

The whole command surface is unit tested without needing a running Ableton Live instance, using lightweight fakes for the Live Object Model (`tests/fakes/live_objects.py`):

```bash
uv pip install -e ".[dev]"
pytest
```

This runs:
- `tests/remote_script/` - every handler, the dispatcher's error handling, and the socket server, all against fakes
- `tests/mcp_server/` - the socket client (`AbletonConnection`) against a real loopback socket, plus every `@mcp.tool` against a fake connection, including a cross-check that every tool sends a command the Remote Script dispatcher actually knows about

`tests/integration/` contains opt-in, read-only tests against a *real* Ableton Live instance (they never create/delete anything, to avoid mutating whatever project happens to be open). They're excluded by default and only run with:

```bash
pytest -m integration tests/integration
```

They're automatically skipped if nothing is listening on `localhost:9877`.

### Known Limitations

Some things Ableton Live's UI can do aren't exposed through the scriptable Live Object Model at all, so they're out of scope here too:

- Freezing/flattening tracks
- Reordering tracks or devices within a chain (the LOM has no "move" call for either)
- Warp mode/markers and detailed audio-clip editing beyond gain and loop points
- Groove pool assignment
- Saving/exporting the project (the LOM does not expose a save call)
- Anything specific to third-party plugin UIs beyond their exposed parameters

Automation envelope support (`clear_clip_envelope`/`insert_envelope_point(s)`) relies on `Clip.automation_envelope`, which has historically had version-to-version quirks in Live's own API; treat it as best-effort and verify results in the Live UI, especially on older Live versions.

## Contributing

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

## Disclaimer

This is a third-party integration and not made by Ableton.
