Sonos MCP Server

Instructions

Implementation Reference

• server.py:143-155 (handler)

  The handler function for the 'pause' MCP tool. It is registered via the @mcp.tool() decorator. Retrieves the specified Sonos device, calls device.pause() to pause playback, and returns the updated device state using get_info_from.

  @mcp.tool()
  def pause(name: Optional[str] = None) -> Dict[str, Any]:
      """Pause playback on a Sonos device.
      
      Args:
          name: The name of the device to pause. If None, uses the current device.
          
      Returns:
          Dict[str, Any]: The device's state after pausing, including name, volume, state, and track info.
      """
      device = get_device(name)
      device.pause()
      return get_info_from(device)

• server.py:64-87 (helper)

  Helper function used by the pause tool to fetch and format the device state after pausing.

  def get_info_from(device: soco.SoCo) -> Dict[str, Any]:
      """Retrieve detailed information from a Sonos device.
      
      Args:
          device: The Sonos device to retrieve information from.
          
      Returns:
          Dict[str, Any]: A dictionary containing the device's name, volume, state, and current track information.
      """
      track_info = device.get_current_track_info()
      return {
          "name": device.player_name,
          "volume": device.volume,
          "state": device.get_current_transport_info()["current_transport_state"],
          "track": {
              "title": track_info.get("title"),
              "artist": track_info.get("artist"),
              "album": track_info.get("album"),
              "position": track_info.get("position"),
              "duration": track_info.get("duration"),
              "playlist_position": track_info.get("playlist_position"),
              "album_art": track_info.get("album_art")
          }
      }

• server.py:31-62 (helper)

  Helper function used by the pause tool to get the Sonos device instance by name or default.

  def get_device(name: Optional[str] = None) -> soco.SoCo:
      """Retrieve a Sonos device by name or return the current device.
      
      Args:
          name: The name of the device to retrieve. If None, returns the current device.
          
      Returns:
          soco.SoCo: The Sonos device object.
          
      Raises:
          ValueError: If the specified device name is not found.
      """
      global device
      if not name and device:
          return device
      
      devices = get_devices()
      if not name:
          device = devices[list(devices.keys())[0]]
          return device
      
      if name in devices:
          device = devices[name]
          return device
      
      for key in devices:
          if key.lower() == name.lower():
              device = devices[key]
              return device
              
      raise ValueError(f"Device {name} not found")