sideman MCP server
Commit Nov 15, 2026Enables AI clients to control Ableton Live via the Live Object Model, allowing for automated music production, MIDI manipulation, and arrangement.
Also known as slegroux/sideman
- Stars
- 2
- Tools
- 5
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 15, 2026
- License
- GPL-3.0
What is sideman MCP?
sideman enables AI clients to control Ableton Live via the Live Object Model, allowing for automated music production, MIDI manipulation, and arrangement. It exposes 5 tools, such as lom_search, lom_describe, lom_transaction.
Summary generated from the project's README
About sideman MCP server
Automating music production and MIDI manipulation within Ableton Live is what sideman enables for developers and musicians using AI clients. By exposing the Live Object Model through a generic path, get, set, and call contract, this server allows an AI to reach any property available in the software without needing manual tool updates for every new release. It works locally by connecting an MCP client like Claude or Codex to a remote script running inside Ableton Live 12.
The server provides 33 tools, including specialized functions for MIDI note management, clip automation, and browser interaction. Users can perform complex tasks such as building house loops from empty sets or analyzing audio files for loudness and spectrum data. Unlike other implementations that hand-write individual tools for every property, this server uses a census-based approach to ensure high coverage of the 983 members found in recent Live versions. It also features unique observers that can report changes made by a user directly in the Ableton GUI.
What you can do with it
- 1Generate musical loopsAn AI can be instructed to build a complete four-bar house loop starting from an entirely empty Ableton Set.
- 2Monitor GUI changesThe server can notify the AI client when a user makes manual adjustments within the Ableton interface.
Written from the project's README. Every use case is checked against a quote from it.
sideman MCP tools 5
Detected from the READMElom_searchlom_describelom_transactionlom_canonical_pathclip_set_warp_markers
Configuration
VIRTUAL_ENV
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableslegroux/sideman is public and reachablegithub.com/slegroux/sideman ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)GPL-3.0spdx.org/licenses/GPL-3.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/slegroux/sideman ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model5 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubAn Ableton Live MCP server with complete Live Object Model coverage.
Every other Ableton MCP server hand-writes one tool per property, so coverage is
bounded by human labour and goes stale each Live release. This one exposes the
Live Object Model itself — the same generic path / get / set / call
contract Max for Live's live.object uses — so any property Live has is
reachable without shipping new code.
- docs/TUTORIAL.md — build a 4-bar house loop from an empty Set. Start here.
- The course — a melodic house track from an empty Set in ten lessons; one path for musicians (prompts only), one for programmers (executed notebooks).
- docs/TOOLS.md — all 33 tools with signatures (generated)
- docs/PROTOCOL.md — wire protocol, threading contract, how to add an op
- docs/CLIENT.md — the
sideman.LivePython client, method by method (generated) - docs/CONVENTIONS.md — paths,
__path__, batches vs transactions, observers, and the gotchas measured against Live - skills/sideman/SKILL.md — path grammar for the model
Why
Live 12.4.6 exposes 47 reachable types / 983 members by measurement (see
baseline/). Coverage is measured, not claimed: a census of the running Live,
and a harness that checks every Live API attribute the Remote Script
competitors touch against it and exits nonzero if any is unaccounted for.
Method, numbers and what is out of scope: docs/COVERAGE.md.
Architecture
Claude ──MCP──► mcp_server/server.py 33 tools
│ JSON/TCP :9878 (not 9877 — coexists with others)
▼
remote_script/AbletonLOM/
├── __init__.py thin socket shell (restart Live to change)
└── handlers.py LOM engine, 29 ops (hot-reload, no restart)
Threading contract: accept-thread → client-thread → schedule_message(0, task).
The Live API is only ever touched on Live's main thread; the client thread blocks
on a Queue. Violating this freezes the GUI.
Hot reload: handlers.py is re-importlib.reloaded by the reload op, so
engine changes need no Live restart. Only the socket shell does.
Install
Live version: any Live 12 edition. 12.4 or later is recommended: that is
where a transaction becomes one Cmd-Z, and where insert_device, insert_chain
and replace_sample exist. On older Live the same tools reach whatever that
Live exposes.
Musicians: download the .pkg from
Releases, open it, and follow the
last screen. It installs into your home folder, needs no password, and brings its
own Python. It is not yet notarized, so the first time macOS will refuse a
double-click: right-click the .pkg → Open → Open. On macOS 15 and later
that prompt is often not offered — open it once, then go to System Settings →
Privacy & Security and click Open Anyway. Developers: the steps below.
git clone <repo> && cd sideman
uv venv --python 3.11 .venv
VIRTUAL_ENV=.venv uv pip install -e . -c constraints.txt # explicit VIRTUAL_ENV, or uv may target a conda env
./scripts/install.sh # symlinks into Ableton's User Library
constraints.txt is the lock, and uv run does not read it. Run things with
.venv/bin/python or ./scripts/…, not uv run. In this checkout uv run
writes a uv.lock of its own (ignored by git) and re-syncs .venv to it, so the
venv drifts off the lock and scripts/test.sh fails its env check. The fix is
the install line above.
Then in Ableton: Preferences → Link, Tempo & MIDI → Control Surface and pick
AbletonLOM in any free slot. Restart Live first if it was running when you
ran install.sh — Live only scans Remote Scripts/ at startup.
Verify and capture the LOM map for your Live version:
./scripts/lomcli.py ping
./scripts/census.py # writes baseline/lom_census_<version>.json
Register with Claude Code — --scope user matters, or the server is only
visible from this directory:
claude mcp add --scope user sideman -- "$PWD/.venv/bin/python" -m mcp_server.server
Or with Codex (the CLI or the ChatGPT desktop app), in ~/.codex/config.toml —
absolute repo path, and keep the entry outside any managed block:
[mcp_servers.sideman]
command = "/absolute/path/to/repo/.venv/bin/python"
args = ["-m", "mcp_server.server"]
type = "stdio"
Optionally install the skill, which teaches the model the path grammar — the one thing per-tool docstrings cannot carry:
./scripts/install.sh --skills # symlinks into ~/.claude/skills and ~/.codex/skills
MCP servers load at client startup — restart your session before the tools appear.
Tools
33 tools. Generic first — the typed ones exist only where generic access genuinely cannot work. Full signatures in docs/TOOLS.md.
| Tool | Purpose |
|---|---|
lom_search |
Find paths by name or type. Start here. |
lom_describe |
Properties, children, functions, per-instance availability |
lom_get / lom_set / lom_call |
Read / write / invoke anything |
lom_get_batch / lom_set_batch |
Many ops, one round trip |
lom_transaction |
Several ops, one undo step (see caveat below) |
lom_canonical_path |
Resolve aliases (view selected_track → tracks 3) |
lom_count / lom_types / lom_ping |
Collection size / census / health |
clip_get_notes / add / modify / remove |
MIDI notes (typed) |
browser_list / browser_load |
Library, incl. VST/AU/VST3 |
clip_envelope_get / insert_step / clear |
Clip automation |
arrangement_create_clip / duplicate_clip / list_clips |
Arrangement authoring |
clip_set_warp_markers |
Audio warp map (typed — JSON cannot carry a WarpMarker) |
lom_observe / lom_poll_events / lom_observers / lom_unobserve* |
Change notification |
audio_analyze / audio_compare / mix_report |
Loudness, peaks, spectrum and stereo of an audio file, vs a reference; per-section report of a capture (local; listen extra) |
Observers are unique to this server. Nothing else in the field reports changes the user makes in the GUI.
Paths
Space-separated, zero-indexed, unquoted:
live_set
live_set tracks 0 mixer_device volume
live_set tracks 2 clip_slots 0 clip
live_app browser instruments
Roots: live_set, live_app, app_view.
Three measured behaviours
Availability is per instance, not per type. A member can exist on a type but
raise on a given object — MIDI tracks have no input_meter_left, only the main
track has a crossfader. lom_describe reports these in an unavailable map
rather than pretending the type list is uniformly gettable.
Undo grouping. lom_transaction collapses its ops into one Cmd-Z. On Live
12.4+ that includes tempo, mixer volume, mute and device parameters. On older
Live those automatable parameters can need extra Cmd-Z, and the result's
undo field says so.
Destructive calls are guarded. Anything named delete_*, remove_* or
clear_*, plus crop, refuses to run unless confirm=true. Derived from a
pattern, not a hand-kept list — the list had drifted, guarding two names Live 12
does not have while missing eleven it does.
Tests
./scripts/test.sh
| Suite | Needs Live | Seam it covers |
|---|---|---|
tests/test_mcp.py |
no | MCP layer with a stubbed socket — op mapping, optional params, safe destructive defaults, error translation |
tests/test_handlers.py |
no | the engine (handlers.py) with a stub Live module and fake objects — undo classes on every mutating result |
tests/test_e2e.py |
yes | MCP layer → socket → Live — the path Claude actually takes |
tests/test_client.py |
yes | the Python client (sideman.client) → Live — the surface the tutorial notebook uses |
tests/smoke.py |
yes | engine via a raw socket — all 29 engine ops (~70s; loads a real device, imports an audio file, cycles scratch tracks) |
The five cover deliberately different seams: test_mcp and test_handlers never touch Live,
smoke never loads the MCP layer, test_client goes through the Python client,
and test_e2e exercises the MCP layer and Live together.
The Live-dependent suites create a scratch MIDI track (__lomtest, or
__sideman_client for the client suite) and delete it, so they work on an
all-audio Set. They refuse to delete a track whose
name changed underneath them, and never touch existing tracks.
CI runs what needs no Live: test_mcp.py, test_handlers.py, the docs check, the dependency-lock
check and the coverage harness. A Remote Script cannot be exercised without its
host, so the other suites are integration by necessity.
Troubleshooting
ConnectionRefusedError / nothing on 9878 — Live is not running, or
AbletonLOM is not selected as a Control Surface. Restarting Live or switching
Sets can clear the slot. Check with:
grep "Control Surface" ~/Library/Preferences/Ableton/Live*/Log.txt | tail -7
claude mcp list says ✔ Connected but tools fail — that tick only means
the stdio process launches. It says nothing about Live. lom_ping is the real
health check.
Tools do not appear at all — MCP servers load at client startup; restart the
session. If they only appear in one directory, the server was registered at
project scope: re-add with --scope user.
uv pip install seems to do nothing — if CONDA_PREFIX is set, uv targets
the conda env instead of .venv. Pass VIRTUAL_ENV=.venv explicitly.
"has no member X" — usually correct. Several properties from older Live
releases are gone in 12 (follow_action_a, fade_in_start, freeze,
create_group_track). lom_describe is the source of truth.
After upgrading Live — rerun ./scripts/census.py. The coverage harness
validates against the census, so a stale one silently checks an API that no
longer exists.
Development
./scripts/lomcli.py ping # health
./scripts/lomcli.py describe "live_set" # explore
./scripts/lomcli.py reload # after editing handlers.py (warns if Live loads an installed copy)
./scripts/census.py # refresh the LOM baseline
./scripts/gen_docs.py # regenerate docs/TOOLS.md and docs/CLIENT.md
./scripts/coverage_harness.py # verify the superset claim
lomcli.py speaks the wire protocol directly, so the engine can be exercised
without the MCP layer in the way. See docs/PROTOCOL.md
for the protocol and how to add an op.
Deliberately no curated per-feature tool layer. The plan called for ~30 sugar verbs; at 33 generic tools that would mean 66, and tool overload degrades selection. The skill buys the same ergonomics at zero tool cost.
License
GPL-3.0-or-later — see LICENSE. Use it, fork it, ship it; a
distributed modification stays open. The Remote Script imports Ableton's own
_MxDCore modules at runtime inside Live, as every Remote Script does; nothing
of Ableton's is in this tree.
sideman MCP questions
What tools does sideman MCP provide?
It exposes 5 tools, including lom_search, lom_describe, lom_transaction, lom_canonical_path, clip_set_warp_markers.
What version of Ableton Live is required?
The server works with any Ableton Live 12 edition, though Live 12.4 or later is recommended for features like transactions and specific insertion tools.
How can I find specific properties or paths in the Live Object Model?
You can use the lom_search tool to find paths by name or type, or lom_describe to see properties, children, and functions available for a specific instance.
Can the server detect changes made manually in the Ableton GUI?
Yes, the server includes unique observers that can report changes made by the user within the Ableton interface.