🌐 **English** | [日本語](README.ja.md)

# 🎹 Ableton MCP

An AI agent that gives you full control over Ableton Live using natural language.

## 🚀 Two Modes

### 1️⃣ MCP Mode (Recommended) - No API Key Required!
Use directly from Claude Desktop. Control Ableton just by chatting - no API key needed.

### 2️⃣ CLI Mode - Standalone
Operate from terminal using your Anthropic API key.

> ⚠️ **Note**: CLI mode is experimental and has not been fully tested.

---

## 🌟 MCP Mode Setup (No API Key Required)

### 1. Installation

```bash
cd ableton-mcp
pip install -e .
```

### 2. Configure Claude Desktop

Edit the Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "ableton-mcp": {
      "command": "python",
      "args": ["-m", "src.mcp_server"],
      "cwd": "/path/to/ableton-mcp"
    }
  }
}
```

⚠️ Replace `cwd` with the actual path to your ableton-mcp folder.

📖 **Windows users**: See [INSTALL_WINDOWS.md](INSTALL_WINDOWS.md) for detailed instructions.

### 3. Install AbletonOSC

**Option A: Max for Live Device (Simple)**
1. Download [AbletonOSC](https://github.com/ideoforms/AbletonOSC/releases)
2. Drag `AbletonOSC.amxd` onto a track in Ableton Live

**Option B: Remote Script (Recommended)**
1. Download from https://github.com/ideoforms/AbletonOSC
2. Place in Remote Scripts folder:
   - **Windows**: `C:\Users\<YourName>\Documents\Ableton\User Library\Remote Scripts\AbletonOSC`
   - **macOS**: `~/Music/Ableton/User Library/Remote Scripts/AbletonOSC`
3. Folder structure: `AbletonOSC\__init__.py` should be directly inside
4. In Ableton Live → Preferences → Link/Tempo/MIDI → Control Surface → Select **AbletonOSC**

### 4. Restart Claude Desktop

After restarting, you can control Ableton directly through chat!

```
You: Create a 4-minute EDM track

Claude: [using generate_arrangement tool]
Generated arrangement...

You: Add trap-style drums

Claude: [using create_drum_track tool]
Created drum track 'Drums'...
```

---

## ✨ Features

### 🥁 Drum/Rhythm Generation
- Basic beats, four-on-floor, trap, breakbeat, D&B
- Custom pattern creation

### 🎹 Melody/Synth Generation
- **Melody**: Scale-based auto-generation (adjustable density and contour)
- **Basslines**: basic, walking, syncopated, octave, arpeggiated
- **Chord progressions**: pop, jazz, sad, epic, dark, edm, lofi, cinematic
- **Arpeggios**: up, down, updown, random (8th/16th/triplet)

### 🔍 Sample Search
- Local library search (Ableton Core Library, Splice, etc.)
- Freesound API support
- Natural language queries

### 🎚️ Mixing Assistance
- Frequency collision detection (kick vs bass, etc.)
- Automatic sidechain compression setup
- EQ suggestions
- Level/dynamics analysis

### 📐 Song Structure Generation
- Genre templates: EDM, House, Techno, D&B, HipHop, Trap, Lo-Fi, Ambient, Pop
- Complete structure: Intro → Buildup → Drop → Breakdown → Outro
- Automatic automation generation

---

## 💻 CLI Mode Usage

### Launch

```bash
# Ableton connection mode
python src/cli.py

# Mock mode (test without Ableton)
python src/cli.py --mock
```

### Example Session

```
╔════════════════════════════════════════════════════════════════╗
║               🎹 Ableton Agent CLI v2.0 🎹                     ║
╚════════════════════════════════════════════════════════════════╝

🎤 You: Create a 4-minute EDM track

🤖 Agent: I'll generate an EDM track arrangement.

🎛️  Executing: generate_arrangement
    Parameters: {"genre": "edm", "duration_minutes": 4.0}
✅ Generated arrangement:

🎵 Untitled Edm
   Tempo: 128 BPM | Key: Am
   Total: 72 bars

📋 Structure:
   [  0] intro        |  8 bars | Energy: ███░░░░░░░
   [  8] buildup      |  8 bars | Energy: █████░░░░░
   [ 16] drop         | 16 bars | Energy: ██████████
   [ 32] breakdown    |  8 bars | Energy: ████░░░░░░
   [ 40] buildup      |  8 bars | Energy: ███████░░░
   [ 48] drop         | 16 bars | Energy: ██████████
   [ 64] outro        |  8 bars | Energy: ███░░░░░░░

🎤 You: Create trap-style drums

🤖 Agent: I'll create a trap-style drum pattern.
🎛️  Executing: create_drum_track
    Parameters: {"pattern_type": "trap", "bars": 2, "name": "Trap Drums"}
✅ Created drum track 'Trap Drums' (pattern: trap, 2 bars)
```

---

## ⌨️ Commands

### Special Commands

| Command | Description |
|---------|-------------|
| `/help` | Show help |
| `/status` | Show project status |
| `/genres` | List available genres |
| `/arrangement` | Show current arrangement |
| `/mock` | Toggle mock mode |
| `/clear` | Clear conversation history |
| `quit` | Exit |

### Natural Language Examples

#### Drums
- "Create a basic drum pattern"
- "Make a 4-bar trap beat"
- "Four on the floor kick"
- "Create a breakbeat"

#### Melody/Bass
- "Create a melody in C minor"
- "Bright pentatonic melody"
- "Syncopated bassline"
- "Add an octave bass"
- "16th note arpeggio"

#### Chords
- "Create a dark chord progression"
- "Jazzy chords"
- "Cinematic chord progression"

#### Samples
- "Search for ethnic percussion"
- "Dark synth 140BPM"
- "Find kick samples"

#### Mixing
- "Analyze the mix"
- "Kick and bass are clashing"
- "It sounds muddy"
- "Set up sidechain"
- "Add reverb"

#### Song Structure
- "Create a 4-minute EDM track"
- "Generate a lo-fi hip hop structure"
- "Make a techno arrangement"

#### Mood
- "Make it darker"
- "Brighten it up"
- "Make it more intense"
- "Chill vibe"

---

## 📁 Project Structure

```
ableton-mcp/
├── .gitignore
├── LICENSE
├── README.md                           # English
├── README.ja.md                        # Japanese
├── INSTALL_WINDOWS.md                  # Windows setup guide
├── pyproject.toml
├── setup.bat                           # Windows setup script
├── claude_desktop_config.example.json  # Example config
└── src/
    ├── __init__.py
    ├── mcp_server.py            # MCP server (for Claude Desktop)
    ├── cli.py                   # CLI interface
    ├── agent.py                 # AI agent (Claude API)
    ├── ableton_osc.py           # Ableton OSC communication
    ├── synth_generator.py       # Melody/bass/chord/arpeggio generation
    ├── sample_search.py         # Sample search engine
    ├── mixing_assistant.py      # Mixing analysis & assistance
    └── arrangement_generator.py # Song structure generation
```

---

## 🔧 Extending

### Adding New Tools

1. Add tool definition to `ABLETON_TOOLS` in `src/agent.py`:

```python
{
    "name": "your_tool_name",
    "description": "Tool description",
    "input_schema": {
        "type": "object",
        "properties": {
            "param1": {"type": "string", "description": "Description"}
        },
        "required": ["param1"]
    }
}
```

2. Add execution logic to `execute_command` in `src/cli.py`:

```python
elif tool == "your_tool_name":
    return self._your_implementation(params)
```

### Adding Genre Templates

Add to `GenreTemplates.TEMPLATES` in `src/arrangement_generator.py`:

```python
"your_genre": {
    "sections": [
        ("intro", 8, 0.3, ["pad"]),
        ("verse", 16, 0.6, ["drums", "bass"]),
        # ...
    ],
    "tempo_range": (100, 120),
    "default_key": "Am",
}
```

---

## 🎛️ Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                     User Input (Natural Language)                │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                     Claude API (Tool Use)                        │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐           │
│  │  Drums   │ │ Melody   │ │ Samples  │ │ Mixing   │ ...       │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘           │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Command Executor                            │
│  ┌────────────────┐  ┌────────────────┐  ┌────────────────┐    │
│  │ SynthGenerator │  │ SampleSearch   │  │ MixingAssist   │    │
│  └────────────────┘  └────────────────┘  └────────────────┘    │
│  ┌────────────────┐  ┌────────────────┐                        │
│  │ ArrangementGen │  │ DrumPattern    │                        │
│  └────────────────┘  └────────────────┘                        │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    OSC Communication                             │
│                      (python-osc)                                │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Ableton Live                                │
│                     (via AbletonOSC)                             │
└─────────────────────────────────────────────────────────────────┘
```

---

## ❓ Troubleshooting

### Startup Order (Important!)
1. **Start Ableton Live first**
2. Confirm AbletonOSC shows "Started AbletonOSC on address ('0.0.0.0', 11000)" in log
3. **Then start Claude Desktop**

### OSC Connection Error
- Check that AbletonOSC is loaded
- Verify port 11000 is available
- Check firewall settings

**Windows - Check ports:**
```powershell
netstat -ano | findstr "11000 11001"
```

**Windows - Check Ableton log:**
```powershell
Get-Content "$env:USERPROFILE\AppData\Roaming\Ableton\Live *\Preferences\Log.txt" -Tail 50 | Select-String "OSC"
```

### Claude Desktop Issues
- **After editing files**: Restart Claude Desktop completely (exit from system tray)
- **Connection problems**: Restart Claude Desktop

### API Error (CLI Mode)
- Verify `ANTHROPIC_API_KEY` is correctly set
- Check API usage limits

### Samples Not Found
- Check sample folder paths
- Specify custom paths when initializing `SampleSearchEngine`

---

## 📄 License

MIT

## 🔗 References

- [AbletonOSC](https://github.com/ideoforms/AbletonOSC)
- [Anthropic Claude API](https://docs.anthropic.com/)
- [python-osc](https://python-osc.readthedocs.io/)
- [Freesound API](https://freesound.org/docs/api/)