🌐 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)

Download AbletonOSC
Drag AbletonOSC.amxd onto a track in Ableton Live

Option B: Remote Script (Recommended)

Download from https://github.com/ideoforms/AbletonOSC
Place in Remote Scripts folder:
- Windows: C:\Users\<YourName>\Documents\Ableton\User Library\Remote Scripts\AbletonOSC
- macOS: ~/Music/Ableton/User Library/Remote Scripts/AbletonOSC
Folder structure: AbletonOSC\__init__.py should be directly inside
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

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"]
    }
}

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!)

Start Ableton Live first
Confirm AbletonOSC shows "Started AbletonOSC on address ('0.0.0.0', 11000)" in log
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

Ableton MCP