DannyQuick/ableton-mcp-extended

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:

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

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:

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

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

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
• Ableton Live API Documentation
• Claude Desktop Setup Guide

Start making music with AI today! 🎵✨