# Ableton MCP Extended

**Complete Claude AI integration for Ableton Live through Model Context Protocol (MCP)**

Control Ableton Live directly from Claude with natural language - create tracks, compose melodies, mix songs, and produce music using AI assistance!

## 🎵 Features

### Session Control
- **Playback Control**: Start/stop playback, control recording
- **Tempo Management**: Set and adjust session tempo
- **Session Info**: Get real-time session status

### Track Management
- **Create Tracks**: MIDI and audio tracks with custom names
- **Track Info**: Get detailed track information including clips and devices
- **Track Control**: Volume, mute, solo, and track naming
- **Track Deletion**: Remove unwanted tracks

### Clip Operations
- **Create Clips**: MIDI clips with custom length and names
- **Add Notes**: Programmatic MIDI note creation with pitch, timing, velocity
- **Clip Control**: Fire, stop, and delete clips
- **Clip Naming**: Organize clips with descriptive names

### Device & Effects
- **Device Info**: Get information about track devices and parameters
- **Parameter Control**: Adjust device parameters programmatically
- **Instrument Loading**: Load instruments and effects from browser

### Browser Integration
- **Browse Content**: Explore Ableton's browser hierarchy
- **Load Instruments**: Load instruments, drum kits, and effects
- **Sample Management**: Access and load samples and packs

## 🚀 Quick Start

### 1. Installation

Run the automated installer:

```bash
cd ableton-mcp-extended
python install_remote_script.py
```

The installer will:
- 🔍 Auto-detect your Ableton Live installation
- 📦 Install the remote script
- ⚙️ Configure Claude Desktop
- 🎯 Set up the Python package

### 2. Ableton Live Setup

1. **Start Ableton Live**
2. **Go to Preferences → MIDI**  
3. **Control Surface**: Select `AbletonMCP_Extended_Remote_Script`
4. **Input/Output**: Leave as "None"

### 3. Claude Desktop Setup

Restart Claude Desktop after installation. The MCP server should appear in your configuration.

### 4. Start Creating Music!

Open Claude and try commands like:

```
"Create a drum track and add a basic beat"
"Add a bass line in C minor"
"Create a chord progression using piano"
"Set the tempo to 128 BPM and start playback"
```

## 🎹 Usage Examples

### Creating a Basic Song Structure

```
Hey Claude, let's create a song:

1. Set the tempo to 120 BPM
2. Create a drum track with a basic 4/4 beat
3. Add a bass track with a simple bass line in C major
4. Create a piano track with a chord progression: C - Am - F - G
5. Start playback so I can hear it
```

### Detailed Music Production

```
I want to create a house track:

1. Set tempo to 128 BPM
2. Create a drum track called "House Drums"
3. Add a classic house beat with:
   - Kick on beats 1 and 3
   - Snare on beats 2 and 4  
   - Hi-hats on every 8th note
4. Create a bass track and add a pumping bass line
5. Add some reverb to the drums and adjust the mix
```

### Live Performance Control

```
During my live set:
1. Mute the bass track
2. Gradually increase the volume of track 3
3. Fire the clip in slot 2 of the drum track
4. Stop all clips and restart from the beginning
```

## 🔧 Manual Installation

If the automatic installer doesn't work, follow these steps:

### 1. Install Python Package

```bash
pip install -e .
```

### 2. Install Remote Script

Copy `AbletonMCP_Extended_Remote_Script` to your Ableton Live MIDI Remote Scripts directory:

**macOS:**
```
/Applications/Ableton Live [Version].app/Contents/App-Resources/MIDI Remote Scripts/
```

**Windows:**
```
C:\Program Files\Ableton\Live [Version]\Resources\MIDI Remote Scripts\
```

### 3. Configure Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "ableton-mcp-extended": {
      "command": "uvx",
      "args": ["ableton-mcp-extended"]
    }
  }
}
```

**Config file locations:**
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `~/AppData/Roaming/Claude/claude_desktop_config.json`  
- **Linux**: `~/.config/claude/claude_desktop_config.json`

## 🧪 Testing

Run the comprehensive test suite:

```bash
# Install test dependencies
pip install pytest pytest-asyncio pytest-timeout

# Run all tests
pytest

# Run specific test categories
pytest tests/test_ableton_connection.py  # Connection tests
pytest tests/test_music_creation.py      # Music creation workflows
pytest tests/test_integration.py         # Integration tests
```

## 🎛️ Available Commands

### Session Commands
- `get_session_info()` - Get tempo, time signature, playback state
- `set_tempo(tempo)` - Set session tempo (20-999 BPM)
- `start_playback()` - Start playback
- `stop_playback()` - Stop playback
- `set_session_record(enabled)` - Enable/disable recording

### Track Commands
- `create_midi_track(name, position)` - Create MIDI track
- `create_audio_track(name, position)` - Create audio track
- `get_track_info(track_index)` - Get track details
- `set_track_name(track_index, name)` - Rename track
- `set_track_volume(track_index, volume)` - Set volume (0.0-1.0)
- `set_track_mute(track_index, mute)` - Mute/unmute track
- `set_track_solo(track_index, solo)` - Solo/unsolo track
- `delete_track(track_index)` - Delete track

### Clip Commands
- `create_clip(track_index, slot_index, length_bars, name)` - Create clip
- `add_notes_to_clip(track_index, slot_index, notes)` - Add MIDI notes
- `set_clip_name(track_index, slot_index, name)` - Rename clip
- `fire_clip(track_index, slot_index)` - Play clip
- `stop_clip(track_index, slot_index)` - Stop clip
- `delete_clip(track_index, slot_index)` - Delete clip

### Browser Commands
- `get_browser_tree()` - Get browser structure
- `get_browser_items(path)` - Get items at path
- `load_browser_item(item_path, track_index)` - Load item
- `load_instrument(name, track_index)` - Load instrument
- `load_drum_kit(name, track_index)` - Load drum kit

### Device Commands
- `get_device_info(track_index, device_index)` - Get device info
- `set_device_parameter(track_index, device_index, param_index, value)` - Set parameter

## 🎼 MIDI Note Format

When adding notes to clips, use this format:

```python
notes = [
    {
        'pitch': 60,        # MIDI note number (60 = C4)
        'time': 0.0,        # Start time in beats
        'duration': 1.0,    # Note length in beats  
        'velocity': 100,    # Velocity (1-127)
        'mute': False       # Optional: mute state
    }
]
```

**Common MIDI Notes:**
- C4 = 60, C#4 = 61, D4 = 62, D#4 = 63, E4 = 64
- F4 = 65, F#4 = 66, G4 = 67, G#4 = 68, A4 = 69
- A#4 = 70, B4 = 71, C5 = 72

**Drum Notes (General MIDI):**
- Kick = 36, Snare = 38, Hi-Hat = 42, Open Hi-Hat = 46
- Crash = 49, Ride = 51

## 🔧 Troubleshooting

### Connection Issues

**"Failed to connect to Ableton"**
1. Ensure Ableton Live is running
2. Check that the remote script is properly installed
3. Verify the remote script is selected in MIDI preferences
4. Try restarting Ableton Live

**"Remote script not appearing in preferences"**
1. Check the script was copied to the correct directory
2. Ensure the `__init__.py` file is present
3. Try refreshing or restarting Ableton Live

### Claude Integration Issues

**"MCP server not found"**
1. Restart Claude Desktop after configuration
2. Check the config file syntax and location
3. Verify the Python package is installed: `pip list | grep ableton-mcp`

**"Commands not working"**
1. Check connection status: Ask Claude "What's the Ableton connection status?"
2. Verify Ableton is running and the remote script is active
3. Check for error messages in Claude

### Performance Issues

**"Slow response times"**
1. Reduce the number of concurrent operations
2. Use smaller clip lengths for testing
3. Check system resources and close other applications

**"Memory usage"**
1. Restart Ableton Live periodically during long sessions
2. Clear unused clips and tracks
3. Monitor system memory usage

## 🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

## 📝 License

MIT License - see LICENSE file for details.

## 🙏 Acknowledgments

- Built on the Model Context Protocol (MCP) by Anthropic
- Inspired by the Ableton Live community
- Uses FastMCP for efficient server implementation

## 🔗 Links

- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
- [Ableton Live API Documentation](https://docs.ableton.com/en/live/liveosc/)
- [Claude Desktop Setup Guide](https://claude.ai/desktop)

---

**Start making music with AI today! 🎵✨**