ableton-mcp

A full-featured Model Context Protocol (MCP) server that gives AI assistants (Claude, etc.) complete control over Ableton Live via AbletonOSC.

Overview

ableton-mcp bridges AI assistants and Ableton Live by exposing 160+ MCP tools covering the full AbletonOSC API: transport, mixing, clips, MIDI notes, devices, scenes, return tracks, browser, groove pool, view navigation, and real-time listeners.

The server communicates with Ableton Live via 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+
• AbletonOSC installed as a MIDI Remote Script

---

Installation

1. Install AbletonOSC in Ableton Live

1. 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
2. Restart Ableton Live
3. Open Preferences → Link, Tempo & MIDI → MIDI and set one of the Control Surface slots to AbletonOSC

AbletonOSC listens on UDP port 11000 and replies on port 11001.

2. Install ableton-mcp

git clone https://github.com/your-user/ableton-mcp
cd ableton-mcp

python -m venv .venv
.venv\Scripts\activate          # Windows
# source .venv/bin/activate     # macOS/Linux

pip install -e .

3. Configure Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "ableton-mcp": {
      "command": "C:\\path\\to\\ableton-mcp\\.venv\\Scripts\\ableton-mcp.exe",
      "args": []
    }
  }
}

Restart Claude Code. Tools appear automatically when a Live session is open.

---

Configuration

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

---

Tool Reference

System (5 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	Average CPU process usage (0.0–1.0)
system_show_message	Display a message in the Ableton status bar
system_reload_api	Hot-reload all AbletonOSC modules

---

Song / Transport (38 tools)

Playback

Tool	Description
song_get_state	Full snapshot: tempo, is_playing, loop, time sig, track/scene/return counts, groove
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_jump_by	Move playhead by ±N beats relative to current position
song_jump_to_next_cue	Jump to next cue point
song_jump_to_prev_cue	Jump to previous cue point
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 & Scenes

Tool	Description
song_get_tracks	List all tracks with index and name
song_get_return_tracks	List all return tracks with index and name
song_create_audio_track / song_create_midi_track / song_create_return_track	Create tracks
song_delete_track / song_delete_return_track / song_duplicate_track	Delete/duplicate tracks
song_get_scenes	List all scenes with index and name
song_create_scene / song_delete_scene / song_duplicate_scene	Scene CRUD

Cue Points

Tool	Description
song_get_cue_points	List all cue points {index, name, time}

---

Tracks (19 tools)

Tool	Description
track_get_info	All properties: name, volume, pan, mute, solo, arm, type, color, monitoring, 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 / track_set_solo / track_set_arm	Mute/solo/arm
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: 0=Auto, 1=In, 2=Off
track_set_fold	Fold/unfold a group track
track_get_clips	Session clips: index, name, length, color, is_playing
track_get_arrangement_clips	Arrangement clips: index, name, length, start_time
track_get_devices	Devices: index, name, type, class_name, can_have_chains
track_get_meter	Output meter: level, left, right, peak_left, peak_right
track_delete_device / track_duplicate_device	Remove/duplicate device
track_get_input_routing	Current input type + channel + available options
track_set_input_routing_type / track_set_input_routing_channel	Set input routing
track_get_output_routing	Current output type + channel + available options
track_set_output_routing_type / track_set_output_routing_channel	Set output routing

---

Return Tracks (11 tools)

Tool	Description
return_track_get_info	All properties: name, mute, solo, color, volume, panning
return_track_set_volume / return_track_set_panning	Volume/pan
return_track_set_mute / return_track_set_solo	Mute/solo
return_track_set_name / return_track_set_color	Rename/recolor
return_track_get_send / return_track_set_send	Inter-return sends
return_track_get_meter	Output meter: level, left, right
return_track_get_devices	List devices on the return track

---

Clips (31 tools)

Playback & Properties

Tool	Description
clip_fire / clip_stop	Launch/stop a clip
clip_get_info	All properties: name, length, playing state, loop, markers, pitch, gain, launch mode
clip_set_name / clip_set_color	Rename/recolor
clip_set_gain	Clip gain in dB
clip_set_muted	Mute/unmute
clip_set_looping / clip_set_loop_points	Enable loop and set start/end
clip_set_markers	Set clip start/end markers
clip_set_pitch	Transpose: semitones (−48…+48) and cents (−50…+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	0=Trigger, 1=Gate, 2=Toggle, 3=Repeat
clip_set_launch_quantization	Per-clip quantization (0–14)
clip_set_legato	Enable/disable legato
clip_set_velocity_amount	Scale note velocities (0.0–1.0)
clip_set_ram_mode	Enable/disable RAM mode for audio clips
clip_duplicate_loop	Double loop by duplicating content
clip_quantize	Quantize MIDI notes (quantization enum + strength 0.0–1.0)

MIDI Notes

Tool	Description
clip_get_notes	Notes filtered by pitch/time range: {pitch, start, duration, velocity, mute}
clip_get_notes_extended	Extended notes with note_id, release_velocity, probability
clip_add_notes	Add notes: [{pitch, start, duration, velocity, mute}, …]
clip_apply_note_modifications	Modify existing notes by note_id
clip_remove_notes	Remove notes in pitch/time range

Automation Envelopes

Tool	Description
clip_get_automation_envelope	Get breakpoints {time, value} for a device param
clip_create_automation_envelope	Create envelope for a device param
clip_clear_envelope	Clear one param's envelope
clip_clear_all_envelopes	Clear all envelopes in a clip

Warp & Groove

Tool	Description
clip_get_warp_markers	Warp markers: {beat_time, sample_time}
clip_get_groove / clip_set_groove	Get/assign groove by name

---

Clip Slots (7 tools)

Tool	Description
clip_slot_get_info	State: has_clip, is_playing, is_triggered, will_record, is_group_slot
clip_slot_fire / clip_slot_stop	Trigger/stop a slot
clip_slot_create_clip	Create empty MIDI clip with given length in beats
clip_slot_delete_clip	Delete the clip in a slot
clip_slot_duplicate_to	Copy clip to another slot
clip_slot_set_stop_button	Enable/disable slot stop button

---

Scenes (9 tools)

Tool	Description
scene_fire	Launch a scene by index
scene_fire_as_selected	Fire scene respecting follow actions
scene_get_info	All properties: name, color, tempo, time sig, is_empty, is_triggered
scene_get_num_clips	Number of clips in the scene
scene_get_clip_slots	Per-slot occupancy: {slot_index, has_clip}
scene_set_name / scene_set_color	Rename/recolor
scene_set_tempo	Override tempo (with enable toggle)
scene_set_time_signature	Override time signature

---

Devices (15 tools)

Tool	Description
device_get_info	Name, type, class_name, num_parameters, is_active
device_get_is_active / device_set_is_active	Get/set bypass state
device_get_parameters	All params: index, name, value, min, max, default_value, is_quantized
device_get_parameter	Single param: name, value, min, max, default_value, value_string
device_set_parameter	Set a parameter value (0.0–1.0 normalized)
device_set_parameters_bulk	Set multiple params: [{index, value}, …]
device_randomize_macros	Randomize rack macro knobs
device_get_chains	Rack chains: index, name, num_devices, device names
device_get_drum_pads	Drum Rack pads: index, name, note, mute, solo
device_set_drum_pad_mute / device_set_drum_pad_solo	Mute/solo a drum pad
device_chain_get_parameter	Get a param value inside a rack chain
device_chain_set_parameter	Set a param value inside a rack chain

---

View / Navigation (8 tools)

Tool	Description
view_get_selection	Selected track, scene, clip, and device
view_get_focused_document_view	Active view name (e.g. 'Session', 'Arranger')
view_set_selected_track	Select a track
view_set_selected_scene	Select a scene
view_set_selected_clip	Select a clip
view_show_clip_detail	Show clip detail panel
view_show_device_detail	Show device detail panel
view_focus_browser	Focus the browser panel

---

Browser (6 tools)

Tool	Description
browser_get_items	List items in a category: audio_effects / instruments / midi_effects / samples / sounds / clips / packs / plugins
browser_load_item	Load an item into the selected track/slot (pass path parts as args)
browser_preview_item	Preview a sample or preset
browser_stop_preview	Stop browser preview playback
browser_get_hotswap_target	Name of device targeted for hotswap
browser_begin_hotswap	Begin hotswap mode for a device

---

Groove Pool (3 tools)

Tool	Description
groove_get_all	List all groove names in the groove pool
groove_get_amount	Get groove intensity (0.0–1.0) by name
groove_set_amount	Set groove intensity (0.0–1.0) by name

---

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

Load a reverb from the browser onto the first return track and set the
wet/dry to 50%.

Get all drum pad names on track 0's Drum Rack, then mute every pad
that isn't a kick or snare.

Solo track 3, set its reverb send to 0.4, and watch the output meter
until it clips.

Set the groove pool's first groove to 80% intensity and assign it to
all clips on track 1.

---

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
    ├── track.py       # Mixing, routing, devices list, meter
    ├── clip.py        # Playback, MIDI notes, pitch, warp, loop, launch, envelopes
    ├── clip_slot.py   # Slot-level create/fire/delete/duplicate
    ├── scene.py       # Scene fire, info, clip slots, tempo/time-sig overrides
    ├── device.py      # Parameters (individual + bulk), chains, drum pads
    ├── return_track.py# Return/aux track mixing and devices
    ├── browser.py     # Content library browsing, load, preview, hotswap
    ├── groove.py      # Groove pool listing and amount control
    ├── view.py        # Selected track/scene/clip, panel navigation
    ├── system.py      # Connectivity, version, CPU, status bar
    └── listener.py    # Real-time property change subscriptions

---

Troubleshooting

system_test_connection returns connected: false

• Confirm AbletonOSC is enabled in Preferences → Control Surfaces
• A Live project must be open (AbletonOSC only activates with an open set)
• Check that no firewall blocks UDP 11000/11001 on localhost

Timeout errors

• Increase ABLETON_TIMEOUT env var (default 5 s)
• song_get_state issues many sequential queries; slow machines may need 10 s+

No module named 'ableton_mcp'

• Install with pip install -e . inside the correct .venv
• The MCP config command path must point to the .venv executable

---

License

MIT