Skip to content

README.md

Latest commit

 

History

History
328 lines (253 loc) · 9.73 KB

README.md

File metadata and controls

328 lines (253 loc) · 9.73 KB

AbletonMCP - Advanced Ableton Live Model Context Protocol Integration

Ableton Live Python MCP License

AbletonMCP connects Ableton Live to Claude AI through the Model Context Protocol (MCP), enabling comprehensive AI-assisted music production, track creation, and Live session manipulation with 37 powerful tools.

🎵 Features

Session Management

  • Session Information: Get detailed session data including tempo, time signature, track counts
  • Playback Control: Start/stop playback with precision
  • Tempo Control: Adjust session tempo in real-time

Track Management

  • Track Creation: Create MIDI and audio tracks
  • Track Operations: Delete, duplicate, and rename tracks
  • Track Control: Arm/disarm for recording, mute/solo functionality
  • Track Information: Get detailed track information and status

Mixing & Audio Controls

  • Volume Control: Adjust individual track volumes
  • Panning Control: Set track panning positions
  • Send Levels: Control send effects and returns
  • Audio Routing: Manage track routing and sends

Clip Management

  • Clip Creation: Create MIDI clips with custom lengths
  • Note Programming: Add MIDI notes with pitch, timing, velocity, and mute control
  • Clip Operations: Copy, delete, and manipulate clips

Scene Management

  • Scene Control: Fire scenes for live performance
  • Scene Creation: Create and delete scenes
  • Scene Organization: Manage scene structure

Recording

  • Recording Control: Start and stop recording
  • Track Arm: Arm tracks for recording
  • Recording Management: Handle recording states

Device Management

  • Device Loading: Add instruments and effects
  • Parameter Control: Adjust device parameters
  • Device Management: Remove devices, activate/deactivate
  • Parameter Discovery: Get device parameter information

🏗️ Architecture

The system consists of two main components:

1. Ableton Remote Script (AbletonMCP_Remote_Script/__init__.py)

A MIDI Remote Script that runs inside Ableton Live, creating a socket server to receive and execute commands from the MCP server.

Key Features:

  • Socket-based communication (localhost:9877)
  • Thread-safe command processing
  • Comprehensive error handling
  • Real-time Ableton Live API integration

2. MCP Server (MCP_Server/server.py)

A Python server implementing the Model Context Protocol, connecting to the Ableton Remote Script and exposing 37 tools to Claude AI.

Key Features:

  • FastMCP implementation
  • Comprehensive tool set
  • Robust error handling
  • Real-time communication

📋 Prerequisites

  • Ableton Live 10 or newer (tested with Live 12.3b9)
  • Python 3.8 or newer
  • Claude Desktop with MCP support
  • Windows/macOS/Linux support

🚀 Installation

Step 1: Clone the Repository

git clone https://github.com/Milesy1/MCP-Ableton-API.git
cd MCP-Ableton-API

Step 2: Install Dependencies

# Install using pip
pip install -e .

# Or install dependencies directly
pip install mcp[cli]>=1.3.0

Step 3: Install the Ableton Remote Script

Windows:

  1. Navigate to one of these locations:

    • C:\Users\[Username]\AppData\Roaming\Ableton\Live x.x.x\Preferences\User Remote Scripts
    • C:\ProgramData\Ableton\Live XX\Resources\MIDI Remote Scripts\
    • C:\Program Files\Ableton\Live XX\Resources\MIDI Remote Scripts\

  2. Create a folder called AbletonMCP

  3. Copy AbletonMCP_Remote_Script/__init__.py into the AbletonMCP folder

macOS:

  1. Navigate to one of these locations:

    • Applications > Right-click Ableton Live > Show Package Contents > Contents/App-Resources/MIDI Remote Scripts/
    • /Users/[Username]/Library/Preferences/Ableton/Live XX/User Remote Scripts

  2. Create a folder called AbletonMCP

  3. Copy AbletonMCP_Remote_Script/__init__.py into the AbletonMCP folder

Step 4: Configure Ableton Live

  1. Launch Ableton Live
  2. Go to Settings/Preferences → Link, Tempo & MIDI
  3. In the Control Surface dropdown, select "AbletonMCP"
  4. Set Input and Output to "None"

Step 5: Configure Claude Desktop

  1. Open Claude Desktop
  2. Go to Settings → Developer → Edit Config
  3. Edit claude_desktop_config.json:
{
    "mcpServers": {
        "AbletonMCP": {
      "command": "python",
      "args": ["C:\\path\\to\\your\\MCP-Ableton-API\\MCP_Server\\server.py"]
        }
    }
}

Note: Replace the path with your actual installation path.

🎛️ Available Tools

Session Tools

  • get_session_info - Get detailed session information
  • set_tempo - Change session tempo
  • start_playback - Start playback
  • stop_playback - Stop playback

Track Tools

  • create_midi_track - Create MIDI tracks
  • create_audio_track - Create audio tracks
  • delete_track - Delete tracks
  • duplicate_track - Duplicate tracks
  • set_track_name - Rename tracks
  • get_track_info - Get track details
  • set_track_arm - Arm/disarm tracks
  • set_track_mute - Mute/unmute tracks
  • set_track_solo - Solo/unsolo tracks

Mixing Tools

  • set_track_volume - Adjust track volumes
  • set_track_panning - Control track panning
  • set_track_send - Adjust send levels

Clip Tools

  • create_clip - Create MIDI clips
  • add_notes_to_clip - Add MIDI notes
  • copy_clip - Copy clips
  • delete_clip - Delete clips

Scene Tools

  • fire_scene - Trigger scenes
  • create_scene - Create scenes
  • delete_scene - Delete scenes

Recording Tools

  • start_recording - Start recording
  • stop_recording - Stop recording

Device Tools

  • add_device - Add instruments/effects
  • remove_device - Remove devices
  • set_device_parameter - Adjust device parameters
  • set_device_active - Enable/disable devices
  • get_device_parameters - Get device parameter info

🎵 Usage Examples

Basic Track Creation

"Create a new MIDI track with a synth bass instrument"
"Add an audio track for vocals"
"Set track 1 to arm for recording"

Mixing and Effects

"Set the volume of track 2 to 80%"
"Pan track 3 to the left (-0.5)"
"Add reverb to track 1 with 30% wet signal"
"Set the master volume to 85%"

MIDI Programming

"Create a 4-bar MIDI clip in track 1"
"Add a C major chord progression to the clip"
"Create a drum pattern with kick on 1 and 3, snare on 2 and 4"

Scene Management

"Create a new scene called 'Verse'"
"Fire scene 2"
"Delete the last scene"

Advanced Composition

"Create a Metro Boomin style hip-hop beat with 808s and hi-hats"
"Build an 80s synthwave track with arpeggiated bass"
"Create a jazz chord progression in track 1"

🔧 Troubleshooting

Connection Issues

  • Ensure Ableton Live is running with the AbletonMCP control surface selected
  • Check that the MCP server path in Claude Desktop config is correct
  • Verify Python dependencies are installed

Tool Not Available

  • Restart Claude Desktop after configuration changes
  • Clear Claude Desktop cache if tools don't appear
  • Check MCP server logs for errors

Timeout Errors

  • Break complex requests into smaller steps
  • Ensure Ableton Live is responsive
  • Check socket connection (localhost:9877)

Performance Issues

  • Close unnecessary Ableton Live tracks
  • Avoid simultaneous complex operations
  • Monitor system resources

🏗️ Development

Project Structure

MCP-Ableton-API/
├── AbletonMCP_Remote_Script/    # Ableton Live Remote Script
│   └── __init__.py
├── MCP_Server/                  # MCP Server Implementation
│   └── server.py
├── pyproject.toml              # Project Configuration
├── README.md                   # This File
├── LICENSE                     # MIT License
├── Dockerfile                  # Container Configuration
└── smithery.yaml              # Smithery Configuration

Adding New Tools

  1. Add command handler in AbletonMCP_Remote_Script/__init__.py
  2. Add tool endpoint in MCP_Server/server.py
  3. Update command routing in the Remote Script
  4. Test and document the new functionality

Testing

# Test MCP server
python -m MCP_Server.server

# Test socket communication
python create_midi.py

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

Code Style

  • Follow PEP 8 for Python code
  • Add comprehensive docstrings
  • Include error handling
  • Update documentation

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

  • Ableton for the amazing Live software and API
  • Anthropic for Claude AI and MCP protocol
  • MCP Community for the Model Context Protocol
  • Contributors who help improve this project

🔗 Links

📞 Support

If you encounter any issues or have questions:

  1. Check the troubleshooting section
  2. Search existing GitHub Issues
  3. Create a new issue with detailed information
  4. Join the discussion in the community

Made with ❤️ for the music production community

Transform your Ableton Live workflow with AI-powered assistance!