# Ableton MCP Enhanced

Control **Ableton Live** from **Cursor** by typing what you want in plain language — create basslines, load Serum, mix tracks, work in Arrangement view, tweak any plugin knob.

> **¿No sos developer?** → Empezá acá: **[Guía de usuario (español)](docs/GUIA_USUARIO.md)**  
> **Not a developer?** → Start here: **[Getting Started](docs/GETTING_STARTED.md)**

Fork and extension of [ableton-mcp](https://github.com/ahujasid/ableton-mcp) by Siddharth Ahuja.

---

## Instalación en un comando

```bash
git clone https://github.com/emaxees/ableton-mcp-enhanced.git
cd ableton-mcp-enhanced
python3 install.py
```

El instalador (`install.py`) funciona en **macOS, Windows y Linux**:
- Prepara Python
- Instala el conector en Ableton Live
- Configura Cursor automáticamente
- Te guía paso a paso

Después: **Ableton → Preferences → Link, Tempo & MIDI → Control Surface → AbletonMCP**

---

## What can you do?

Ask Cursor things like:

- *"What's my session tempo?"*
- *"Create a rolling bassline in C# in Arrangement view"*
- *"Load Serum on track 5 and set cutoff to 0.35"*
- *"Mute the kick and solo the bass"*

Full list: **[Qué podés hacer](docs/QUE_PUEDES_HACER.md)** | **[What you can do (EN)](docs/WHAT_YOU_CAN_DO.md)**

---

## Features

- **Session & transport** — tempo, playback, track/scene info
- **MIDI** — create tracks, clips, add notes (Session + Arrangement)
- **Arrangement view** — clips directly on the timeline
- **Plugins (VST/AU)** — Serum, any plugin via path or extension
- **Full device control** — list/set any automatable parameter
- **Mixer** — volume, pan, mute, solo, arm
- **Batch commands** — multiple operations in one shot
- **Plugin extensions** — YAML manifests for friendly names & macros

---

## Documentation

| Audience | Document |
|----------|----------|
| **Productores / no devs (ES)** | [docs/GUIA_USUARIO.md](docs/GUIA_USUARIO.md) |
| **Non-developers (EN)** | [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md) |
| **Qué se puede controlar** | [docs/QUE_PUEDES_HACER.md](docs/QUE_PUEDES_HACER.md) |
| **Plugin extensions** | [docs/EXTENSIONS.md](docs/EXTENSIONS.md) |
| **All MCP tools** | [docs/TOOLS.md](docs/TOOLS.md) |
| **Problems & fixes** | [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) |

---

## Architecture

```
Cursor  ◄──MCP──►  MCP Server (Python)  ◄──TCP :9877──►  Remote Script in Live
```

Extension YAML files map friendly names (`filter_cutoff`) to Live parameter names.

---

## Requirements

- Ableton Live **11 or 12**
- **Python 3.10+**
- **Cursor** ([cursor.com](https://cursor.com))

---

## Manual install (developers)

<details>
<summary>Click to expand manual steps</summary>

```bash
git clone https://github.com/emaxees/ableton-mcp-enhanced.git
cd ableton-mcp-enhanced
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e .
./scripts/install-remote-script.sh   # Windows: python install.py
```

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "AbletonMCP": {
      "command": "/absolute/path/to/ableton-mcp-enhanced/scripts/run-mcp.sh",
      "args": []
    }
  }
}
```

Windows: use `.venv\Scripts\python.exe` with `"args": ["-m", "MCP_Server.server"]`

</details>

---

## Project structure

```
ableton-mcp-enhanced/
├── install.py                  ← Start here (auto installer)
├── AbletonMCP_Remote_Script/   ← Runs inside Ableton
├── MCP_Server/                 ← MCP server for Cursor
├── extensions/plugins/         ← Plugin manifests (Serum, etc.)
├── docs/GUIA_USUARIO.md        ← Non-dev guide (Spanish)
└── scripts/
```

---

## Environment variables

| Variable | Default | Description |
|----------|---------|-------------|
| `ABLETON_HOST` | `localhost` | Remote Script host |
| `ABLETON_PORT` | `9877` | Remote Script port |
| `ABLETON_MCP_EXTENSIONS_DIR` | — | Extra plugin extension folder |

---

## Limitations

- Controls everything **Ableton's API exposes** (parameters, clips, tracks, browser, transport)
- Does **not** automate plugin GUI windows (e.g. dragging wavetables in Serum)
- Only **one MCP client** at a time (Cursor *or* Claude, not both)

---

## Credits & license

- Based on [ableton-mcp](https://github.com/ahujasid/ableton-mcp) by Siddharth Ahuja
- Enhanced by [emaxees](https://github.com/emaxees)
- **MIT License** — see [LICENSE](LICENSE)