Content
# philtzjp/live-connector
<img src="https://github.com/philtzjp/.github/blob/main/images/philtz.png?raw=true" width="150px" alt="Philtz Logo">
live-connector is a Cypher-style MCP server that lets AI agents query and edit an Ableton Live Set, built on the Ableton Extensions SDK.
## Overview
This project allows an external AI agent to read and write Ableton Live Sets (tracks, clips, devices, MIDI notes, device parameters, etc.) by hosting an MCP server within the Ableton Live Extensions SDK (a Node.js process that runs alongside Live).
The Live Object Model (LOM) is treated as a property graph, and access is performed using declarative queries in a Cypher subset. Instead of having a large number of tools for each type, the design focuses on expressing capabilities through the query language and schema introspection, allowing agents to find and perform operations autonomously.
```cypher
-- Example: Read the Cutoff of the Operator in the "Drums" track
MATCH (:Track {name:"Drums"})-[:HAS_DEVICE]->(:Device {name:"Operator"})-[:HAS_PARAM]->(p:Parameter {name:"Cutoff"})
RETURN p.value, p.min, p.max
```
## Setup and Startup
> **Important:** The Ableton Extensions SDK is not included in this repository. Please obtain it from Ableton and place it in `ableton-sdk/` (which is `.gitignore`d).
### Prerequisites
- When using an installed `.ablx`: Ableton Live (Extensions-enabled beta build)
- When generating or development-launching `.ablx` from the repository: Node.js (Extension Host uses bundled runtime ≥ 24.14.1) + pnpm
- When generating or development-launching `.ablx` from the repository: Ableton Extensions SDK distribution (`ableton-create-extension` / `ableton-extensions-sdk` / `ableton-extensions-cli`) placed in `ableton-sdk/`
### Generating a distributable `.ablx`
The distributable archive is generated using the SDK CLI's `extensions-cli package`. After installing dependencies in the repository root and running the package task, a production build will generate `apps/extension/dist/live-connector-2.0.0.ablx`.
```sh
pnpm install
pnpm package
```
The output file name is determined from `name` and `version` in `apps/extension/manifest.json`. The `.ablx` includes `manifest.json` and `dist/extension.js` pointed to by `manifest.entry`.
### Installation and Usage (CLI not required)
1. Prepare a generated or distributed `live-connector-2.0.0.ablx`.
2. Open Ableton Live's Preferences → Extensions, and drop the `.ablx` into the Extensions page to install it.
3. Set Preferences → Extensions' **Developer Mode** to OFF.
4. Restart Ableton Live.
5. When Live starts, the Extension Host will automatically load the installed extension, and `MCP HTTP server listening ... :7799` will appear in the Max Window.
6. Connect from the MCP client to `http://127.0.0.1:7799/api/v1/mcp`.
- Health check: `http://127.0.0.1:7799/health`
- `/api/v1/mcp` allows only loopback Host and Origin header
In installation-based operation, `extensions-cli run` and `pnpm --filter @live-connector/extension start` are not required. If `LIVE_CONNECTOR_MCP_HOST` and `LIVE_CONNECTOR_MCP_PORT` are not set, `127.0.0.1:7799` is used.
### Registering with Claude Code
To register with Claude Code, add the HTTP MCP server once with project scope. For versions #35 and later, the Authorization header is not required.
```sh
claude mcp add --transport http live-connector http://127.0.0.1:7799/api/v1/mcp --scope project
```
After MCP settings changes, such as registration or URL changes, restart Claude Code. If Live is restarted or the extension is reinstalled without changing the URL, Claude Code will automatically reconnect to the same endpoint.
If managing with `.mcp.json` (`.gitignore`d), place the following configuration in the project root:
```json
{
"mcpServers": {
"live-connector": {
"type": "http",
"url": "http://127.0.0.1:7799/api/v1/mcp"
}
}
}
```
### Updates
1. Run `pnpm package` in the repository root to generate a new `apps/extension/dist/live-connector-2.0.0.ablx`.
2. Drop the new `.ablx` in Ableton Live's Preferences → Extensions to update the existing live-connector.
3. Restart Ableton Live.
4. If the URL remains `http://127.0.0.1:7799/api/v1/mcp`, Claude Code does not require re-registration or restart. Restart Claude Code only if MCP settings are changed.
### Development Mode (Fast Reload)
Developer Mode stops the Extension Host managed by Live and allows developers to start the Extension Host with `extensions-cli run`. This mode is used for development with short cycles of change confirmation.
1. Create `apps/extension/.env` (`.gitignore`d).
```
EXTENSION_HOST_PATH=/Applications/Ableton Live 12 Beta.app # Path to your Live installation
LIVE_CONNECTOR_MCP_HOST=127.0.0.1
LIVE_CONNECTOR_MCP_PORT=7799
```
2. Launch Live and set **Developer Mode** to ON in Preferences → Extensions.
3. Build and start the extension.
```sh
pnpm --filter @live-connector/extension start
```
4. On success, `MCP HTTP server listening ... :7799` will appear in the Max Window.
Change reflections in development mode are done by CLI start. In installation-based operation, changes are reflected by repackaging, reinstalling `.ablx`, and restarting Live.
## Preset Exploration and Device State
Ableton Extensions SDK v1.0.0-beta.0 does not have a Browser API, `BrowserItem`, or APIs to load native presets for `.adv` / `.adg` / third-party plug-ins. `search_presets` only lists preset candidates under the specified root and does not apply them to Live or plug-ins.
The host-exposed parameters of inserted devices can be saved to JSON in `environment.storageDirectory/device-states/` with `save_device_state` and reapplied to the same parameters with `apply_device_state`. This is limited to values exposed as `DeviceParameter` to the SDK, and non-public internal states or waveform selections of third-party plug-ins like Serum are not saved or restored.
## Directory Structure
```text
.
├── apps/
│ └── extension/ # Ableton Extension (MCP server main body, bundled with esbuild to cjs)
├── packages/
│ ├── cypher/ # Cypher subset parser and evaluator (SDK-independent)
│ ├── lom-schema/ # Single definition of LOM graph schema
│ ├── env/ # Environment variable collection (zod)
│ ├── log/ # Log collection
│ ├── error/ # Error collection (RFC 9457 / MCP error conversion)
│ └── tsconfig/ # Shared TypeScript configuration
├── ableton-sdk/ # Ableton-provided SDK suite (not included, gitignore)
├── AGENTS.md # Work regulations for AI agents (CLAUDE.md is a symlink)
├── .agents/skills/ # Master skills adopted (`.claude/skills` is a relative symlink)
├── lefthook.yaml # Pre-commit / commit message verification
├── turbo.json / pnpm-workspace.yaml
├── LICENSE # MIT (homemade parts) + Ableton SDK's third-party clause
└── README.md
```
## License
The **original code, documentation, and assets in this repository are [MIT](./LICENSE)**.
However, **Ableton Extensions SDK is © Ableton AG and not MIT**. The SDK is a third-party component subject to the Ableton Extensions SDK License, and it is not included in this repository (with `ableton-sdk/` `.gitignore`d). You need to obtain it from Ableton separately. See [LICENSE](./LICENSE) for details on Third-Party Components.
