ableton-mcp/README.md

# ableton-mcp

A full-featured [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that gives AI assistants (Claude, etc.) complete control over Ableton Live via [AbletonOSC](https://github.com/ideoforms/AbletonOSC).

## Overview

**ableton-mcp** bridges AI assistants and Ableton Live by exposing **124 MCP tools** covering every major area of the Live API: transport control, track mixing, clip launching and editing, MIDI note manipulation, device parameter control, scene management, view selection, and real-time property listeners.

The server communicates with Ableton Live via [AbletonOSC](https://github.com/ideoforms/AbletonOSC) — a MIDI Remote Script that runs inside Live and exposes its internal API over OSC/UDP.

```
Claude (AI) ──MCP tools──▶ ableton-mcp ──OSC/UDP──▶ AbletonOSC ──Live Object Model──▶ Ableton Live
```

---

## Requirements

- **Ableton Live 11 or later**
- **Python 3.10+** (tested with 3.10.6 via pyenv)
- **AbletonOSC** installed as a MIDI Remote Script (see below)

---

## Installation

### 1. Install AbletonOSC in Ableton Live

1. Download or clone [AbletonOSC](https://github.com/ideoforms/AbletonOSC)
2. Copy the `AbletonOSC` folder into your Ableton User Library Remote Scripts directory:
   - **Windows:** `%USERPROFILE%\Documents\Ableton\User Library\Remote Scripts`
   - **macOS:** `~/Music/Ableton/User Library/Remote Scripts`
3. Restart Ableton Live
4. Open **Preferences → Link, Tempo & MIDI → MIDI** and set one of the Control Surface slots to **AbletonOSC**

AbletonOSC will now listen on **UDP port 11000** and reply on **port 11001**.

### 2. Install ableton-mcp

```bash
# Clone the repo (rename the folder after cloning)
git clone https://github.com/your-user/ableton-mcp
cd ableton-mcp

# Create and activate a virtual environment
python -m venv .venv
.venv\Scripts\activate          # Windows
# source .venv/bin/activate     # macOS/Linux

# Install
pip install -e .
```

### 3. Configure Claude Desktop

Add the server to your Claude Desktop configuration file:

**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`  
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "ableton": {
      "command": "C:\\path\\to\\ableton-mcp\\.venv\\Scripts\\ableton-mcp.exe"
    }
  }
}
```

Restart Claude Desktop. The Ableton Live tools will appear automatically when a Live session is open.

---

## Configuration

All settings can be overridden via environment variables:

| Variable | Default | Description |
|---|---|---|
| `ABLETON_HOST` | `127.0.0.1` | AbletonOSC host address |
| `ABLETON_SEND_PORT` | `11000` | Port to send OSC commands to Live |
| `ABLETON_RECEIVE_PORT` | `11001` | Port to receive OSC replies from Live |
| `ABLETON_TIMEOUT` | `5.0` | Query timeout in seconds |

Example (Claude Desktop config with custom port):
```json
{
  "mcpServers": {
    "ableton": {
      "command": "C:\\path\\to\\.venv\\Scripts\\ableton-mcp.exe",
      "env": {
        "ABLETON_TIMEOUT": "10.0"
      }
    }
  }
}
```

---

## Tool Reference

### System (7 tools)

| Tool | Description |
|---|---|
| `system_test_connection` | Ping AbletonOSC; returns `{connected, latency_ms}` |
| `system_get_version` | Get Ableton Live version `{major, minor}` |
| `system_get_cpu_usage` | Get average CPU process usage (0.0–1.0) |
| `system_show_message` | Display a message in the Ableton status bar |
| `system_get_log_level` | Get current AbletonOSC log level |
| `system_set_log_level` | Set log level: `debug` / `info` / `warning` / `error` / `critical` |
| `system_reload_api` | Hot-reload all AbletonOSC modules |

---

### Song / Transport (48 tools)

#### Playback
| Tool | Description |
|---|---|
| `song_get_state` | Full snapshot: tempo, is_playing, loop, time sig, track/scene counts, groove, link, scale… |
| `song_start_playing` | Start playback from current position |
| `song_stop_playing` | Stop playback |
| `song_continue_playing` | Resume without resetting to start |
| `song_stop_all_clips` | Stop all active clips |
| `song_tap_tempo` | Send a tap-tempo pulse |

#### Tempo & Time
| Tool | Description |
|---|---|
| `song_get_tempo` / `song_set_tempo` | Get/set BPM (20–300) |
| `song_get_time` / `song_set_time` | Get/jump playhead position in beats |
| `song_get_time_signature` / `song_set_time_signature` | Get/set numerator + denominator |

#### Loop
| Tool | Description |
|---|---|
| `song_get_loop` | Get `{loop, loop_start, loop_length}` |
| `song_set_loop` | Set on/off, start, and length (beats) |

#### Metronome, Quantization & Groove
| Tool | Description |
|---|---|
| `song_get_metronome` / `song_set_metronome` | Toggle metronome |
| `song_set_quantization` | Clip trigger quantization (0=none … 13=1/32) |
| `song_set_midi_recording_quantization` | MIDI recording quantization |
| `song_set_groove` | Global groove amount (0.0–1.0) |

#### Recording
| Tool | Description |
|---|---|
| `song_set_arrangement_overdub` | Enable/disable arrangement overdub |
| `song_set_session_record` | Enable/disable session record |
| `song_set_punch_in` / `song_set_punch_out` | Punch in/out |
| `song_trigger_session_record` | Toggle session record |
| `song_capture_midi` | Capture incoming MIDI into a new clip |
| `song_re_enable_automation` | Re-enable overridden automation |

#### Edit
| Tool | Description |
|---|---|
| `song_undo` / `song_redo` | Undo/redo |

#### Tracks
| Tool | Description |
|---|---|
| `song_get_tracks` | List all tracks with index and name |
| `song_create_audio_track` | Create audio track at index |
| `song_create_midi_track` | Create MIDI track at index |
| `song_create_return_track` | Create return/aux track |
| `song_delete_track` / `song_delete_return_track` | Delete track |
| `song_duplicate_track` | Duplicate a track |

#### Scenes
| Tool | Description |
|---|---|
| `song_get_scenes` | List all scenes with index and name |
| `song_create_scene` / `song_delete_scene` / `song_duplicate_scene` | Scene CRUD |
| `song_capture_and_insert_scene` | Capture session state as a new scene |

#### Cue Points
| Tool | Description |
|---|---|
| `song_get_cue_points` | List all cue points |
| `song_jump_to_cue` | Jump to cue by index or name |
| `song_add_or_delete_cue` | Toggle cue at current playhead |
| `song_set_cue_name` | Rename a cue point |

#### Scale & Link
| Tool | Description |
|---|---|
| `song_set_root_note` | Set root note (0=C … 11=B) |
| `song_set_scale_name` | Set scale name e.g. `"Major"`, `"Dorian"` |
| `song_set_ableton_link` | Enable/disable Ableton Link |
| `song_export_structure` | Export full session structure to JSON file |

---

### Tracks (19 tools)

| Tool | Description |
|---|---|
| `track_get_info` | All track properties: name, volume, pan, mute, solo, arm, type, color, monitoring, meter slots, device count |
| `track_set_volume` | Volume (0.0=−∞, 0.85≈0 dB, 1.0=+6 dB) |
| `track_set_pan` | Panning (−1.0=left, 0.0=center, +1.0=right) |
| `track_set_mute` | Mute / unmute |
| `track_set_solo` | Solo / unsolo |
| `track_set_arm` | Arm / disarm for recording |
| `track_get_send` / `track_set_send` | Get/set send level to a return track |
| `track_set_name` | Rename a track |
| `track_set_color` | Set track color by palette index (0–69) |
| `track_stop_clips` | Stop all clips on a track |
| `track_set_monitoring` | Monitoring state: 0=Auto, 1=In, 2=Off |
| `track_set_fold` | Fold/unfold a group track |
| `track_get_clips` | List session clips: index, name, length, color |
| `track_get_arrangement_clips` | List arrangement clips: index, name, length, start_time |
| `track_get_devices` | List devices: index, name, type, class_name |
| `track_get_meter` | Output meter levels: left, right, level |
| `track_delete_device` | Remove a device from the chain |
| `track_get_available_input_routing_types` | List available input routing options |
| `track_set_input_routing_type` / `track_set_output_routing_type` | Set I/O routing |

---

### Clips (19 tools)

| Tool | Description |
|---|---|
| `clip_fire` | Launch a clip |
| `clip_stop` | Stop a playing clip |
| `clip_get_info` | All clip properties: name, length, playing state, loop, markers, pitch, gain, launch mode, warp, color |
| `clip_set_name` | Rename a clip |
| `clip_set_color` | Set clip color by palette index (0–69) |
| `clip_set_gain` | Set clip gain in dB |
| `clip_set_muted` | Mute/unmute a clip |
| `clip_set_looping` | Enable/disable loop |
| `clip_set_loop_points` | Set loop start + end in beats |
| `clip_set_markers` | Set start + end markers in beats |
| `clip_set_pitch` | Transpose: semitones (−48 to +48) and cents (−50 to +50) |
| `clip_set_warp_mode` | Warp mode: 0=Beats, 1=Tones, 2=Texture, 3=Re-Pitch, 4=Complex, 5=Complex Pro |
| `clip_set_warping` | Enable/disable warping |
| `clip_set_launch_mode` | Launch mode: 0=Trigger, 1=Gate, 2=Toggle, 3=Repeat |
| `clip_set_launch_quantization` | Per-clip launch quantization (0–14) |
| `clip_set_legato` | Enable/disable legato mode |
| `clip_duplicate_loop` | Double loop length by duplicating content |
| `clip_get_notes` | Get MIDI notes (filterable by pitch range + time range) |
| `clip_add_notes` | Add MIDI notes: `[{pitch, start, duration, velocity, mute}, …]` |
| `clip_remove_notes` | Remove MIDI notes by pitch/time range |

---

### Clip Slots (7 tools)

| Tool | Description |
|---|---|
| `clip_slot_get_info` | Slot state: has_clip, is_playing, is_triggered, will_record, is_group_slot |
| `clip_slot_fire` | Trigger a slot (launches clip or starts recording if empty) |
| `clip_slot_stop` | Stop a slot |
| `clip_slot_create_clip` | Create a new empty MIDI clip with a given length in beats |
| `clip_slot_delete_clip` | Delete the clip in a slot |
| `clip_slot_duplicate_to` | Copy clip from one slot to another |
| `clip_slot_set_stop_button` | Enable/disable the stop button for a slot |

---

### Scenes (7 tools)

| Tool | Description |
|---|---|
| `scene_fire` | Launch a scene by index |
| `scene_fire_selected` | Launch the currently selected scene |
| `scene_get_info` | All scene properties: name, color, tempo, tempo_enabled, time sig, is_empty, is_triggered |
| `scene_set_name` | Rename a scene |
| `scene_set_color` | Set scene color by palette index (0–69) |
| `scene_set_tempo` | Override tempo for a scene (with enable toggle) |
| `scene_set_time_signature` | Override time signature for a scene |

---

### Devices (6 tools)

| Tool | Description |
|---|---|
| `device_get_info` | Device info: name, type (audio_effect / instrument / midi_effect), class_name, num_parameters |
| `device_get_parameters` | All parameters: index, name, value, min, max, is_quantized |
| `device_get_parameter` | Single parameter: name, value, value_string (display value) |
| `device_set_parameter` | Set a parameter value (normalized 0.0–1.0) |
| `device_set_parameters_bulk` | Set multiple parameters in one call: `[{index, value}, …]` |
| `device_map_midi_cc` | Map a MIDI CC to a device parameter |

---

### View / Selection (5 tools)

| Tool | Description |
|---|---|
| `view_get_selection` | Current selection: selected_track, selected_scene, selected_clip, selected_device |
| `view_set_selected_track` | Select a track in the Ableton UI |
| `view_set_selected_scene` | Select a scene in the Ableton UI |
| `view_set_selected_clip` | Select a clip in the Ableton UI |
| `view_set_selected_device` | Select a device in the Ableton UI |

---

### Real-time Listeners (3 tools)

Subscribe to property changes from Ableton Live and poll them at any time.

| Tool | Description |
|---|---|
| `listener_start` | Register a listener for a property; returns the OSC response address |
| `listener_stop` | Unregister a listener |
| `listener_get_events` | Drain queued events (up to `max_events`); each event is a list of OSC args |

**Supported objects and properties:**

| object_type | property_name | Notes |
|---|---|---|
| `song` | `beat` | `[beat_number, beat_index, bar, song_time]` per beat |
| `song` | `is_playing` | `[0/1]` |
| `song` | `tempo` | `[bpm]` |
| `song` | `current_song_time` | `[beats]` |
| `view` | `selected_track` | `[track_index]` |
| `view` | `selected_scene` | `[scene_index]` |
| `track` | any read/write property | requires `track_index` |
| `clip` | any read/write property | requires `track_index` + `clip_index` |
| `clip_slot` | any property | requires `track_index` + `clip_index` |

**Example usage with Claude:**
> "Watch the beat and tell me the bar number every 4 bars"  
> Claude calls `listener_start("song", "beat")`, then periodically `listener_get_events("song", "beat")`

---

## Example Prompts

```
Play the song from bar 3 at 128 BPM with the metronome on.

Create a 4-bar MIDI clip on track 0, slot 1, and add a C minor chord
(C3, Eb3, G3) on beats 1 and 3 with velocity 90.

Set every device on track 2 to a random-ish sound: 
randomize all parameters whose name contains "Filter".

Loop scene 4 forever: set scene 4's clips to looping and fire the scene.

Solo track 3, mute tracks 1 and 2, and set track 3's reverb send to 0.4.

Name all empty scenes "—" and delete any track with no clips.
```

---

## Architecture

```
src/ableton_mcp/
├── server.py        # FastMCP app; registers all tool modules
├── osc_client.py    # Thread-safe OSCClient singleton
│                    #   cmd()   – fire-and-forget
│                    #   query() – synchronous request/response
│                    #   start_listener() / drain_listener() – real-time events
├── config.py        # Port/host/timeout from env vars
└── tools/
    ├── song.py      # Transport, tempo, loop, scenes, tracks, cues, scale, Link
    ├── track.py     # Mixing, routing, devices list, meter
    ├── clip.py      # Playback, MIDI notes, pitch, warp, loop, launch
    ├── clip_slot.py # Slot-level create/fire/delete/duplicate
    ├── scene.py     # Scene fire, tempo/time-sig overrides
    ├── device.py    # Parameter get/set (individual + bulk), MIDI CC mapping
    ├── view.py      # Selected track/scene/clip/device
    ├── system.py    # Connectivity, version, CPU, status bar, logging
    └── listener.py  # Real-time property change subscriptions
```

**OSC communication** uses `python-osc` directly against AbletonOSC's full 200+ endpoint API. The `OSCClient` singleton runs a `ThreadingOSCUDPServer` on the receive port in a daemon thread. Queries use `threading.Event` for synchronous blocking with configurable timeout. Listeners store events in per-address `collections.deque` instances for thread-safe polling.

---

## Troubleshooting

**`system_test_connection` returns `connected: false`**
- Confirm AbletonOSC is enabled in Ableton → Preferences → Control Surfaces
- Make sure a Live project is open (AbletonOSC only activates with an open set)
- Check that no firewall is blocking UDP 11000/11001 on localhost

**Timeout errors on queries**
- Increase `ABLETON_TIMEOUT` env var (default 5 s)
- Some properties (e.g. `song_get_state`) issue many sequential OSC queries; slow machines may need a higher timeout

**`No module named 'ableton_mcp'`**
- Make sure you installed with `pip install -e .` inside the correct `.venv`
- The Claude Desktop config `command` path must point to the `.venv` executable, not the system Python

---

## License

MIT