installation_process.txt

================================================================================
  AbletonBridge - Installation Process Guide
  Ableton Live Model Context Protocol Integration
  Version 3.5.0
================================================================================

PREREQUISITES
--------------------------------------------------------------------------------
Before starting, make sure you have the following installed:

  - Ableton Live 10 or newer (11+ recommended, 12 for full feature support)
  - Python 3.10 or newer
  - uv package manager (https://docs.astral.sh/uv/getting-started/installation/)
  - Claude Desktop, Claude.ai, or Cursor (as your AI assistant / MCP host)
  - Node.js (only if using Smithery auto-install)


================================================================================
STEP 1: INSTALL THE UV PACKAGE MANAGER
================================================================================

  Windows (PowerShell):
    powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

  macOS (Homebrew):
    brew install uv

  Linux / macOS (curl):
    curl -LsSf https://astral.sh/uv/install.sh | sh

Verify installation:
    uv --version

*** Do NOT proceed before uv is installed. ***


================================================================================
STEP 2: INSTALL THE ABLETON REMOTE SCRIPT
================================================================================

This script runs INSIDE Ableton Live and creates a socket server so the MCP
server can send commands to Ableton.

  1. Locate the "AbletonBridge_Remote_Script" folder inside the ableton-bridge
     directory. It contains "__init__.py" and a "handlers/" subdirectory with
     modular handler files (session.py, clips.py, devices.py, etc.).

  2. Copy the entire "AbletonBridge_Remote_Script" folder to one of these
     locations (keep the folder structure intact — __init__.py + handlers/):

     WINDOWS (try in order until one works):
       C:\Users\<YourUsername>\Documents\Ableton\User Library\Remote Scripts\
       C:\Users\<YourUsername>\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\
       (Replace XX with your Ableton version number, e.g. 11, 12)

     macOS:
       Method 1: Applications > Right-click Ableton Live > Show Package Contents >
                 Contents/App-Resources/MIDI Remote Scripts/
       Method 2: /Users/<YourUsername>/Library/Preferences/Ableton/Live XX/User Remote Scripts/

     RECOMMENDED (Live 10.1.13+ / Live 12):
       Place in the User Library Remote Scripts folder:
         Windows: %USERPROFILE%\Documents\Ableton\User Library\Remote Scripts\
         macOS:   ~/Music/Ableton/User Library/Remote Scripts/

  3. The final path should look like:
       ...\Remote Scripts\AbletonBridge\__init__.py
       ...\Remote Scripts\AbletonBridge\handlers\session.py  (etc.)

  4. Launch Ableton Live (or restart it if already open).

  5. Go to Settings/Preferences > Link, Tempo & MIDI.

  6. In the "Control Surface" dropdown, select "AbletonBridge".

  7. Set both Input and Output to "None".


================================================================================
STEP 3: CONFIGURE YOUR AI ASSISTANT (MCP HOST)
================================================================================

--- Option A: Claude Desktop ---

  1. Open Claude Desktop.
  2. Go to Claude > Settings > Developer > Edit Config.
  3. This opens the file "claude_desktop_config.json". Add or merge:

     {
       "mcpServers": {
         "AbletonBridge": {
           "command": "uv",
           "args": ["run", "--directory", "C:\\path\\to\\ableton-bridge", "ableton-bridge"]
         }
       }
     }

     Replace "C:\\path\\to\\ableton-bridge" with the actual path to
     your downloaded/cloned repository folder.

  4. Save the file and restart Claude Desktop.

--- Option B: Claude Code (CLI) ---

  Add to your Claude Code MCP settings:

     {
       "mcpServers": {
         "AbletonBridge": {
           "command": "uv",
           "args": ["run", "--directory", "C:\\path\\to\\ableton-bridge", "ableton-bridge"]
         }
       }
     }

--- Option C: Cursor ---

  1. Go to Cursor Settings > MCP.
  2. Add a new server with the command:

     uv run --directory C:\path\to\ableton-bridge ableton-bridge

  3. Save and restart Cursor.

*** Only run ONE instance of the MCP server (either Claude Desktop OR Cursor),
    not both at the same time. ***


================================================================================
STEP 4: ALTERNATIVE - INSTALL VIA SMITHERY (AUTO-INSTALL)
================================================================================

If you prefer automated setup for Claude Desktop:

    npx -y @smithery/cli install @ahujasid/ableton-mcp --client claude

This handles the Claude Desktop config automatically.


================================================================================
STEP 5: ALTERNATIVE - INSTALL FROM SOURCE (PIP)
================================================================================

If you cloned/downloaded the repo and want to install locally:

    cd C:\path\to\ableton-bridge
    pip install -e .

Or using uv:

    cd C:\path\to\ableton-bridge
    uv pip install -e .

Then configure your MCP host to point to the installed script name
"ableton-bridge".


================================================================================
STEP 6: INSTALL THE MAX FOR LIVE BRIDGE (OPTIONAL)
================================================================================

The M4L bridge provides access to hidden/non-automatable device parameters.
It is optional but required for snapshot, morph, macro, and preset tools.

  1. Requires Ableton Live Suite or Standard + Max for Live.
  2. Open the pre-built M4L device from the M4L_Device folder,
     or create a new Max Audio Effect and build the patch:
       [udpreceive 9878] -> [js m4l_bridge.js] -> [udpsend localhost 9879]
     NOTE: The bridge is an Audio Effect (not MIDI Effect) so it can access
     audio analysis and cross-track metering features.
  3. Copy M4L_Device/m4l_bridge.js to the device's folder.
  4. Save the device and load it on any track.
  5. See M4L_Device/README.md for detailed instructions.


================================================================================
STEP 7: VERIFY THE CONNECTION
================================================================================

  1. Make sure Ableton Live is running with the AbletonBridge control surface active.
  2. Make sure your AI assistant (Claude/Cursor) is running with the MCP config.
  3. In Claude, you should see a hammer icon indicating the AbletonBridge tools
     are available.
  4. Open the web dashboard at http://127.0.0.1:9880 to verify connection status.
  5. Test with a simple command like: "Get information about my Ableton session"

  NOTE: The server maintains a disk-persisted browser cache at
  ~/.ableton-bridge/browser_cache.json.gz (6,400+ items, gzip compressed).
  On first launch, it scans Ableton's instrument/effect library (~10 seconds)
  and saves the cache to disk. Subsequent launches load instantly (~50ms).
  The cache has a 7-day lifetime and auto-refreshes in the background.
  You can force a re-scan with the "refresh_browser_cache" tool after
  installing new packs or instruments.


================================================================================
STEP 8: OPTIONAL - ELEVENLABS VOICE & SFX SERVER
================================================================================

AbletonBridge includes an optional ElevenLabs integration with 19 tools for
AI voice generation, sound effects, voice cloning, and transcription. Generated
audio saves directly to your Ableton User Library for easy import.

  1. Install dependencies:
       pip install -e ".[elevenlabs]"

  2. Set your API key:
       Windows:  set ELEVENLABS_API_KEY=your_key_here
       macOS:    export ELEVENLABS_API_KEY=your_key_here
     Or add to a .env file in the project root.

  3. Add to your MCP host config as a second server alongside AbletonBridge:

     {
       "mcpServers": {
         "AbletonBridge": {
           "command": "uv",
           "args": ["run", "--directory", "C:\\path\\to\\ableton-bridge", "ableton-bridge"]
         },
         "elevenlabs": {
           "command": "uv",
           "args": ["run", "elevenlabs-mcp"],
           "env": {
             "ELEVENLABS_API_KEY": "your_key_here"
           }
         }
       }
     }

  Example commands:
    "Generate a robot voice saying 'drop the bass' and load it into Simpler"
    "Create thunder sound effect, 3 seconds long"
    "Transcribe the audio clip on my desktop"


================================================================================
TROUBLESHOOTING
================================================================================

  Connection issues:
    - Ensure the AbletonBridge Remote Script is loaded in Ableton (check
      Preferences > Link, Tempo & MIDI).
    - Ensure the MCP server config is correct in your AI assistant.
    - The server communicates via TCP socket on localhost (127.0.0.1:9877).

  "unexpected argument '--dir'" error:
    - Use "--directory" instead of "--dir" in your config. Newer versions of
      uv renamed this flag.

  Timeout errors:
    - Simplify your requests or break them into smaller steps.

  Tools not appearing:
    - Restart both Ableton Live AND your AI assistant.
    - Double-check that uv is installed and on your PATH.

  Python version issues:
    - Ensure Python 3.10+ is installed: python --version
    - If using multiple Python versions, specify the correct one in your config.

  Dashboard not loading:
    - Check that Claude Desktop is running the server (restart after config change).
    - If port 9880 is in use, set ABLETON_BRIDGE_DASHBOARD_PORT env var.

  General fix:
    - Restart both Claude/Cursor and Ableton Live.
    - Always save your Ableton project before experimenting.


================================================================================
USEFUL LINKS
================================================================================

  GitHub:   https://github.com/BuggedPlayer/ableton-bridge
  Discord:  https://discord.gg/3ZrMyGKnaU
  uv:       https://docs.astral.sh/uv/getting-started/installation/
  License:  MIT

================================================================================