ableton-agent

A Bun workspace with two packages:

• packages/ableton-agent — the TypeScript library (Live/Song/Track/Clip/Device) plus the two OSC transports it can talk to: the Python AbletonAgent remote script (the primary transport — everything goes through it) and the Max for Live bridge.js device (auxiliary, generic get/set/call only).

• packages/ableton-agent-mcp — an MCP server exposing the library as tools for an LLM agent, following the DAW tool spec in .claude/references/daw_mcp_tool_specs.md where the Live Object Model supports it: session state, tempo/signature/key, transport, tracks & mixer, devices & parameters, clips, and low-level MIDI note editing.

To install dependencies:

bun install

Run a package's script from the root with --filter, e.g.:

bun run --filter ableton-agent test
bun run --filter ableton-agent check-agent
bun run --filter ableton-agent-mcp start

Running the MCP server

The server needs a running Ableton Live session with:

• The AbletonAgent remote script (required — the sole transport) — symlink or copy packages/ableton-agent/remote-script/AbletonAgent into Ableton's User Library Remote Scripts folder (e.g. ~/Music/Ableton/User Library/Remote Scripts/AbletonAgent on macOS), then enable AbletonAgent as a Control Surface in Live's Link/Tempo/MIDI preferences (ports 9010/9011). Once enabled it's active for every project, on any Live edition. Live only loads remote scripts at startup, so restart Live after editing __init__.py.

• The Max for Live bridge (optional, auxiliary) — load packages/ableton-agent/max/ableton-agent.amxd onto any track in your Live set (fixed ports 9000/9001). It speaks the same generic get/set/call protocol and stays available for raw access and diagnostics, but nothing in the library or MCP server requires it.

With one or both running, sanity-check connectivity:

bun run --filter ableton-agent check-agent

Then start the MCP server:

bun run --filter ableton-agent-mcp start

It speaks MCP over stdio, so it's meant to be launched by an MCP client rather than left running in a terminal. To wire it into Claude Desktop, add it to claude_desktop_config.json:

{
  "mcpServers": {
    "ableton-agent": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/ableton-agent/packages/ableton-agent-mcp/index.ts"]
    }
  }
}

Both transports default to fixed local ports; override with env vars if you've changed either side:

Related MCP server: ableton-mind

Testing

bun test (or the commands above) runs two kinds of tests:

• Fake-backed tests (live.test.ts, packages/ableton-agent-mcp/index.test.ts) exercise the library and every MCP tool against an in-memory stand-in for Ableton (testSupport/fakeAbleton.ts) that speaks the real OSC wire protocol. These always run and never touch a real Live session.

• packages/ableton-agent-mcp/index.real.test.ts exercises every MCP tool against a real, running Ableton Live session — with the AbletonAgent remote script enabled. There's no opt-in flag and no skipping: every test always attempts its real call and reports a genuine pass or fail. This means plain bun test requires Ableton to be open, and will start real, audible playback. If Ableton isn't reachable, or a specific backend/feature isn't available, the affected tests fail with a message explaining what's missing — see packages/ableton-agent/check-agent.ts to debug connectivity.

  All mutations are confined to a scratch MIDI track it creates and deletes; global properties it touches (tempo, time signature, key, playhead) are saved and restored.

This project was created using bun init in bun v1.3.14. Bun is a fast all-in-one JavaScript runtime.