🌐 English | 日本語

🎹 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

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

{
  "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 for detailed instructions.

3. Install AbletonOSC

Option A: Max for Live Device (Simple)

1. Download AbletonOSC
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

# 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:

{
    "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:

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

Adding Genre Templates

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

"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:

netstat -ano | findstr "11000 11001"

Windows - Check Ableton log:

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
• Anthropic Claude API
• python-osc
• Freesound API