# AbletonMCP - Advanced Ableton Live Model Context Protocol Integration

![Ableton Live](https://img.shields.io/badge/Ableton-Live-orange)
![Python](https://img.shields.io/badge/Python-3.8+-blue)
![MCP](https://img.shields.io/badge/MCP-Compatible-green)
![License](https://img.shields.io/badge/License-MIT-yellow)

AbletonMCP connects Ableton Live to Claude AI through the Model Context Protocol (MCP), enabling comprehensive AI-assisted music production, track creation, and Live session manipulation with **37 powerful tools**.

## 🎵 Features

### **Session Management**
- **Session Information**: Get detailed session data including tempo, time signature, track counts
- **Playback Control**: Start/stop playback with precision
- **Tempo Control**: Adjust session tempo in real-time

### **Track Management**
- **Track Creation**: Create MIDI and audio tracks
- **Track Operations**: Delete, duplicate, and rename tracks
- **Track Control**: Arm/disarm for recording, mute/solo functionality
- **Track Information**: Get detailed track information and status

### **Mixing & Audio Controls**
- **Volume Control**: Adjust individual track volumes
- **Panning Control**: Set track panning positions
- **Send Levels**: Control send effects and returns
- **Audio Routing**: Manage track routing and sends

### **Clip Management**
- **Clip Creation**: Create MIDI clips with custom lengths
- **Note Programming**: Add MIDI notes with pitch, timing, velocity, and mute control
- **Clip Operations**: Copy, delete, and manipulate clips

### **Scene Management**
- **Scene Control**: Fire scenes for live performance
- **Scene Creation**: Create and delete scenes
- **Scene Organization**: Manage scene structure

### **Recording**
- **Recording Control**: Start and stop recording
- **Track Arm**: Arm tracks for recording
- **Recording Management**: Handle recording states

### **Device Management**
- **Device Loading**: Add instruments and effects
- **Parameter Control**: Adjust device parameters
- **Device Management**: Remove devices, activate/deactivate
- **Parameter Discovery**: Get device parameter information

## 🏗️ Architecture

The system consists of two main components:

### 1. **Ableton Remote Script** (`AbletonMCP_Remote_Script/__init__.py`)
A MIDI Remote Script that runs inside Ableton Live, creating a socket server to receive and execute commands from the MCP server.

**Key Features:**
- Socket-based communication (localhost:9877)
- Thread-safe command processing
- Comprehensive error handling
- Real-time Ableton Live API integration

### 2. **MCP Server** (`MCP_Server/server.py`)
A Python server implementing the Model Context Protocol, connecting to the Ableton Remote Script and exposing 37 tools to Claude AI.

**Key Features:**
- FastMCP implementation
- Comprehensive tool set
- Robust error handling
- Real-time communication

## 📋 Prerequisites

- **Ableton Live 10 or newer** (tested with Live 12.3b9)
- **Python 3.8 or newer**
- **Claude Desktop** with MCP support
- **Windows/macOS/Linux** support

## 🚀 Installation

### Step 1: Clone the Repository

```bash
git clone https://github.com/Milesy1/MCP-Ableton-API.git
cd MCP-Ableton-API
```

### Step 2: Install Dependencies

```bash
# Install using pip
pip install -e .

# Or install dependencies directly
pip install mcp[cli]>=1.3.0
```

### Step 3: Install the Ableton Remote Script

#### **Windows:**
1. Navigate to one of these locations:
   - `C:\Users\[Username]\AppData\Roaming\Ableton\Live x.x.x\Preferences\User Remote Scripts`
   - `C:\ProgramData\Ableton\Live XX\Resources\MIDI Remote Scripts\`
   - `C:\Program Files\Ableton\Live XX\Resources\MIDI Remote Scripts\`

2. Create a folder called `AbletonMCP`
3. Copy `AbletonMCP_Remote_Script/__init__.py` into the `AbletonMCP` folder

#### **macOS:**
1. Navigate to one of these locations:
   - `Applications > Right-click Ableton Live > Show Package Contents > Contents/App-Resources/MIDI Remote Scripts/`
   - `/Users/[Username]/Library/Preferences/Ableton/Live XX/User Remote Scripts`

2. Create a folder called `AbletonMCP`
3. Copy `AbletonMCP_Remote_Script/__init__.py` into the `AbletonMCP` folder

### Step 4: Configure Ableton Live

1. Launch Ableton Live
2. Go to **Settings/Preferences → Link, Tempo & MIDI**
3. In the **Control Surface** dropdown, select **"AbletonMCP"**
4. Set **Input** and **Output** to **"None"**

### Step 5: Configure Claude Desktop

1. Open Claude Desktop
2. Go to **Settings → Developer → Edit Config**
3. Edit `claude_desktop_config.json`:

```json
{
    "mcpServers": {
        "AbletonMCP": {
      "command": "python",
      "args": ["C:\\path\\to\\your\\MCP-Ableton-API\\MCP_Server\\server.py"]
        }
    }
}
```

**Note:** Replace the path with your actual installation path.

## 🎛️ Available Tools

### **Session Tools**
- `get_session_info` - Get detailed session information
- `set_tempo` - Change session tempo
- `start_playback` - Start playback
- `stop_playback` - Stop playback

### **Track Tools**
- `create_midi_track` - Create MIDI tracks
- `create_audio_track` - Create audio tracks
- `delete_track` - Delete tracks
- `duplicate_track` - Duplicate tracks
- `set_track_name` - Rename tracks
- `get_track_info` - Get track details
- `set_track_arm` - Arm/disarm tracks
- `set_track_mute` - Mute/unmute tracks
- `set_track_solo` - Solo/unsolo tracks

### **Mixing Tools**
- `set_track_volume` - Adjust track volumes
- `set_track_panning` - Control track panning
- `set_track_send` - Adjust send levels

### **Clip Tools**
- `create_clip` - Create MIDI clips
- `add_notes_to_clip` - Add MIDI notes
- `copy_clip` - Copy clips
- `delete_clip` - Delete clips

### **Scene Tools**
- `fire_scene` - Trigger scenes
- `create_scene` - Create scenes
- `delete_scene` - Delete scenes

### **Recording Tools**
- `start_recording` - Start recording
- `stop_recording` - Stop recording

### **Device Tools**
- `add_device` - Add instruments/effects
- `remove_device` - Remove devices
- `set_device_parameter` - Adjust device parameters
- `set_device_active` - Enable/disable devices
- `get_device_parameters` - Get device parameter info

## 🎵 Usage Examples

### **Basic Track Creation**
```
"Create a new MIDI track with a synth bass instrument"
"Add an audio track for vocals"
"Set track 1 to arm for recording"
```

### **Mixing and Effects**
```
"Set the volume of track 2 to 80%"
"Pan track 3 to the left (-0.5)"
"Add reverb to track 1 with 30% wet signal"
"Set the master volume to 85%"
```

### **MIDI Programming**
```
"Create a 4-bar MIDI clip in track 1"
"Add a C major chord progression to the clip"
"Create a drum pattern with kick on 1 and 3, snare on 2 and 4"
```

### **Scene Management**
```
"Create a new scene called 'Verse'"
"Fire scene 2"
"Delete the last scene"
```

### **Advanced Composition**
```
"Create a Metro Boomin style hip-hop beat with 808s and hi-hats"
"Build an 80s synthwave track with arpeggiated bass"
"Create a jazz chord progression in track 1"
```

## 🔧 Troubleshooting

### **Connection Issues**
- Ensure Ableton Live is running with the AbletonMCP control surface selected
- Check that the MCP server path in Claude Desktop config is correct
- Verify Python dependencies are installed

### **Tool Not Available**
- Restart Claude Desktop after configuration changes
- Clear Claude Desktop cache if tools don't appear
- Check MCP server logs for errors

### **Timeout Errors**
- Break complex requests into smaller steps
- Ensure Ableton Live is responsive
- Check socket connection (localhost:9877)

### **Performance Issues**
- Close unnecessary Ableton Live tracks
- Avoid simultaneous complex operations
- Monitor system resources

## 🏗️ Development

### **Project Structure**
```
MCP-Ableton-API/
├── AbletonMCP_Remote_Script/    # Ableton Live Remote Script
│   └── __init__.py
├── MCP_Server/                  # MCP Server Implementation
│   └── server.py
├── pyproject.toml              # Project Configuration
├── README.md                   # This File
├── LICENSE                     # MIT License
├── Dockerfile                  # Container Configuration
└── smithery.yaml              # Smithery Configuration
```

### **Adding New Tools**
1. Add command handler in `AbletonMCP_Remote_Script/__init__.py`
2. Add tool endpoint in `MCP_Server/server.py`
3. Update command routing in the Remote Script
4. Test and document the new functionality

### **Testing**
```bash
# Test MCP server
python -m MCP_Server.server

# Test socket communication
python create_midi.py
```

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

### **Development Setup**
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

### **Code Style**
- Follow PEP 8 for Python code
- Add comprehensive docstrings
- Include error handling
- Update documentation

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- **Ableton** for the amazing Live software and API
- **Anthropic** for Claude AI and MCP protocol
- **MCP Community** for the Model Context Protocol
- **Contributors** who help improve this project

## 🔗 Links

- [GitHub Repository](https://github.com/Milesy1/MCP-Ableton-API)
- [Ableton Live](https://www.ableton.com/en/live/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Claude AI](https://claude.ai/)

## 📞 Support

If you encounter any issues or have questions:

1. Check the [troubleshooting section](#troubleshooting)
2. Search existing [GitHub Issues](https://github.com/Milesy1/MCP-Ableton-API/issues)
3. Create a new issue with detailed information
4. Join the discussion in the community

---

**Made with ❤️ for the music production community**

*Transform your Ableton Live workflow with AI-powered assistance!*