AbletonMCP

Instructions

Implementation Reference

• MCP_Server/server.py:410-439 (handler)

  The primary handler for the 'load_instrument_or_effect' MCP tool. It forwards the request to the Ableton remote script via the 'load_browser_item' command.

  @mcp.tool()
  def load_instrument_or_effect(ctx: Context, track_index: int, uri: str) -> str:
      """
      Load an instrument or effect onto a track using its URI.
      
      Parameters:
      - track_index: The index of the track to load the instrument on
      - uri: The URI of the instrument or effect to load (e.g., 'query:Synths#Instrument%20Rack:Bass:FileId_5116')
      """
      try:
          ableton = get_ableton_connection()
          result = ableton.send_command("load_browser_item", {
              "track_index": track_index,
              "item_uri": uri
          })
          
          # Check if the instrument was loaded successfully
          if result.get("loaded", False):
              new_devices = result.get("new_devices", [])
              if new_devices:
                  return f"Loaded instrument with URI '{uri}' on track {track_index}. New devices: {', '.join(new_devices)}"
              else:
                  devices = result.get("devices_after", [])
                  return f"Loaded instrument with URI '{uri}' on track {track_index}. Devices on track: {', '.join(devices)}"
          else:
              return f"Failed to load instrument with URI '{uri}'"
      except Exception as e:
          logger.error(f"Error loading instrument by URI: {str(e)}")
          return f"Error loading instrument by URI: {str(e)}"

• MCP_Server/server.py:411-418 (schema)

  Function signature and docstring defining the input schema (track_index: int, uri: str) and output (str response).

  def load_instrument_or_effect(ctx: Context, track_index: int, uri: str) -> str:
      """
      Load an instrument or effect onto a track using its URI.
      
      Parameters:
      - track_index: The index of the track to load the instrument on
      - uri: The URI of the instrument or effect to load (e.g., 'query:Synths#Instrument%20Rack:Bass:FileId_5116')
      """

• AbletonMCP_Remote_Script/__init__.py:726-760 (helper)

  Low-level helper in the Ableton remote script that implements the actual loading of browser items (instruments/effects) onto tracks, called by the MCP server's forwarded command.

  def _load_browser_item(self, track_index, item_uri):
      """Load a browser item onto a track by its URI"""
      try:
          if track_index < 0 or track_index >= len(self._song.tracks):
              raise IndexError("Track index out of range")
          
          track = self._song.tracks[track_index]
          
          # Access the application's browser instance instead of creating a new one
          app = self.application()
          
          # Find the browser item by URI
          item = self._find_browser_item_by_uri(app.browser, item_uri)
          
          if not item:
              raise ValueError("Browser item with URI '{0}' not found".format(item_uri))
          
          # Select the track
          self._song.view.selected_track = track
          
          # Load the item
          app.browser.load_item(item)
          
          result = {
              "loaded": True,
              "item_name": item.name,
              "track_name": track.name,
              "uri": item_uri
          }
          return result
      except Exception as e:
          self.log_message("Error loading browser item: {0}".format(str(e)))
          self.log_message(traceback.format_exc())
          raise

• AbletonMCP_Remote_Script/__init__.py:761-801 (helper)

  Recursive helper function in the Ableton remote script to locate a browser item by its URI across the browser tree.

  def _find_browser_item_by_uri(self, browser_or_item, uri, max_depth=10, current_depth=0):
      """Find a browser item by its URI"""
      try:
          # Check if this is the item we're looking for
          if hasattr(browser_or_item, 'uri') and browser_or_item.uri == uri:
              return browser_or_item
          
          # Stop recursion if we've reached max depth
          if current_depth >= max_depth:
              return None
          
          # Check if this is a browser with root categories
          if hasattr(browser_or_item, 'instruments'):
              # Check all main categories
              categories = [
                  browser_or_item.instruments,
                  browser_or_item.sounds,
                  browser_or_item.drums,
                  browser_or_item.audio_effects,
                  browser_or_item.midi_effects
              ]
              
              for category in categories:
                  item = self._find_browser_item_by_uri(category, uri, max_depth, current_depth + 1)
                  if item:
                      return item
              
              return None
          
          # Check if this item has children
          if hasattr(browser_or_item, 'children') and browser_or_item.children:
              for child in browser_or_item.children:
                  item = self._find_browser_item_by_uri(child, uri, max_depth, current_depth + 1)
                  if item:
                      return item
          
          return None
      except Exception as e:
          self.log_message("Error finding browser item by URI: {0}".format(str(e)))
          return None