AbletonMCP

# AbletonMCP - Advanced Ableton Live Model Context Protocol Integration     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 ```bash git clone https://github.com/Milesy1/MCP-Ableton-API.git cd MCP-Ableton-API ``` ### Step 2: Install Dependencies ```bash # 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`: ```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** ```bash # 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](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 - [GitHub Repository](https://github.com/Milesy1/MCP-Ableton-API) - [Ableton Live](https://www.ableton.com/en/live/) - [Model Context Protocol](https://modelcontextprotocol.io/) - [Claude AI](https://claude.ai/) ## 📞 Support If you encounter any issues or have questions: 1. Check the [troubleshooting section](#troubleshooting) 2. Search existing [GitHub Issues](https://github.com/Milesy1/MCP-Ableton-API/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!*