Metadata-Version: 2.4
Name: ableton-live-mcp-server
Version: 0.1.4
Summary: MCP Server for Ableton Live
Project-URL: Homepage, https://github.com/mrmos/ableton-live-mcp-server
Project-URL: Issues, https://github.com/mrmos/ableton-live-mcp-server/issues
Author: Project Contributors
License: MIT License
        
        Copyright (c) 2025 Simon Kansara
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.10
Requires-Dist: fastmcp
Requires-Dist: python-osc
Requires-Dist: uvicorn
Description-Content-Type: text/markdown

# Ableton Live MCP Server

## 📌 Overview
The **Ableton Live MCP Server** is a server implementing the [Model Context Protocol (MCP)](https://modelcontextprotocol.io) to facilitate communication between LLMs and **Ableton Live**. It uses **OSC (Open Sound Control)** to send and receive messages to/from Ableton Live.
It is based on [AbletonOSC](https://github.com/ideoforms/AbletonOSC) implementation and exhaustively maps available OSC adresses to [**tools**](https://modelcontextprotocol.io/docs/concepts/tools) accessible to MCP clients.


[![ontrol Ableton Live with LLMs](https://img.youtube.com/vi/12MzsQ3V7cs/hqdefault.jpg)](https://www.youtube.com/watch?v=12MzsQ3V7cs)

This project consists of two main components:
- `mcp_ableton_server.py`: The MCP server handling the communication between clients and the OSC daemon.
- `osc_daemon.py`: The OSC daemon responsible for relaying commands to Ableton Live and processing responses.

## ✨ Features
- Provides an MCP-compatible API for controlling Ableton Live from MCP clients.
- Uses **python-osc** for sending and receiving OSC messages.
- Based on the OSC implementation from [AbletonOSC](https://github.com/ideoforms/AbletonOSC).
- Implements request-response handling for Ableton Live commands.

## ⚡ Installation

### Option 1: Install with UV (Recommended)

1. Install UV if you don't have it already:
   ```bash
   pip install uv
   ```

2. Install directly from PyPI:
   ```bash
   uv install ableton-live-mcp-server
   ```

3. Or install from GitHub:
   ```bash
   uv install git+https://github.com/mrmos/ableton-live-mcp-server.git
   ```

### Option 2: Manual Installation

1. Install `uv`
   ```bash
   pip install uv
   ```
2. Clone the repository:
   ```bash
   git clone https://github.com/your-username/mcp_ableton_server.git
   cd mcp_ableton_server
   ```
3. Install dependencies:
   ```bash
   uv install python-osc fastmcp
   ```
4. Install the MCP Server
   This assumes that you're using [Claude Desktop](https://claude.ai/download)
   ```bash
   mcp install mcp_ableton_server.py
   ```
5. Install AbletonOSC
   Follow the instructions at [AbletonOSC](https://github.com/ideoforms/AbletonOSC)
   
## 🚀 Usage

### Running with a Single Command (Recommended)

The easiest way to start the Ableton Live MCP Server is with the included launcher script:

```bash
# Basic usage (runs both components with default settings)
ableton-mcp-start

# Show debug output from both components
ableton-mcp-start --debug

# Customize ports if needed
ableton-mcp-start --osc-port 65432 --mcp-port 8000 --ableton-port 11000 --receive-port 11001
```

The launcher automatically:
1. Starts the OSC daemon first
2. Verifies that it's running properly
3. Starts the MCP server
4. Monitors both processes and shuts them down gracefully on exit

### Manual Starting (Advanced)

Alternatively, you can manually start each component in separate terminal windows:

### Step 1: Run the OSC Daemon
First, start the OSC daemon to handle OSC communication between the MCP server and Ableton Live:
```bash
ableton-osc-daemon
```
This will:
- Listen for MCP client connections on port **65432**.
- Forward messages to Ableton Live via OSC on port **11000**.
- Receive OSC responses from Ableton on port **11001**.

### Step 2: Run the MCP Server
In a separate terminal window, start the MCP server to enable LLMs to control Ableton:
```bash
ableton-mcp-server
```

### Example Usage
In Claude desktop, ask Claude:
*Prepare a set to record a rock band*
*Set the input routing channel of all tracks that have "voice" in their name to Ext. In 2*

## ⚙️ Configuration
By default, the server and daemon run on **localhost (127.0.0.1)** with the following ports:
- **MCP Server Socket:** 65432
- **Ableton Live OSC Port (Send):** 11000
- **Ableton Live OSC Port (Receive):** 11001

To modify these, edit the `AbletonOSCDaemon` class in `osc_daemon.py` or use command-line parameters:
```bash
ableton-osc-daemon --socket-port 65432 --ableton-port 11000 --receive-port 11001
```

### Claude Desktop Configuration

To configure Claude Desktop to use Ableton Live MCP Server:

1. Edit the Claude Desktop configuration file:
   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - Windows: `%APPDATA%/Claude/claude_desktop_config.json`

2. Add the following to your configuration:

```json
"mcpServers": {
  "Ableton Live Controller": {
    "command": "ableton-mcp-start",
    "args": []
  }
}
```

3. For debugging with visible output:

```json
"mcpServers": {
  "Ableton Live Controller": {
    "command": "ableton-mcp-start",
    "args": ["--debug"]
  }
}
```

4. Restart Claude Desktop

## Contributing
Feel free to submit issues, feature requests, or pull requests to improve this project.

## Publishing Updates
To publish new versions using UV:

1. Update the version in `pyproject.toml`
2. Build the package:
   ```bash
   uv build
   ```
3. Publish to PyPI:
   ```bash
   uv publish
   ```

## License
This project is licensed under the **MIT License**. See the `LICENSE` file for details.

## Acknowledgments
- [Model Context Protocol (MCP)](https://modelcontextprotocol.io)
- [python-osc](https://github.com/attwad/python-osc) for OSC handling
- Daniel John Jones for OSC implementation with [AbletonOSC](https://github.com/ideoforms/AbletonOSC)
- Ableton Third Party Remote Scripts
- Julien Bayle @[Structure Void](https://structure-void.com/) for endless inspirations and resources.

## TODO
- Explore *resources* and *prompts* primitives opportunities.
- Build a standalone Ableton Live MCP client.

---

