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 talks to: the Max for Live bridge.js device (generic get/set/call) and the Python AbletonAgent remote script (browsing, loading, MIDI notes).
• 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 to talk to, via at least one of:

• The Max for Live bridge — load packages/ableton-agent/max/ableton-agent.amxd onto any track in your Live set. It wraps bridge.js and listens on fixed ports 9000/9001. Handles everything except browsing, loading, and MIDI note editing.
• The AbletonAgent remote script — 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). Required for list_instruments/list_browser_category/browse/load_from_browser and the write_midi_notes/get_midi_notes/transpose_notes family — the Max bridge doesn't implement those. Live only loads remote scripts at startup, so restart Live (or toggle the control surface off/on) after editing __init__.py.

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:

Env var	Default	Transport
ABLETON_MAX_ADDRESS	127.0.0.1	Max bridge
ABLETON_MAX_LOCAL_PORT	9001	Max bridge
ABLETON_MAX_REMOTE_PORT	9000	Max bridge
ABLETON_AGENT_ADDRESS	127.0.0.1	AbletonAgent
ABLETON_AGENT_LOCAL_PORT	9011	AbletonAgent
ABLETON_AGENT_REMOTE_PORT	9010	AbletonAgent

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 max/bridge.js and the AbletonAgent remote script both 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.