Spotify MCP Server

Instructions

Implementation Reference

• src/spotify_mcp/server.py:53-64 (schema)

  Pydantic model defining the input schema for the SpotifyPlayback tool, including action (get/start/pause/skip), spotify_uri, and num_skips parameters.

  class Playback(ToolModel):
      """Manages the current playback with the following actions:
      - get: Get information about user's current track.
      - start: Starts playing new item or resumes current playback if called with no uri.
      - pause: Pauses current playback.
      - skip: Skips current track.
      """
      action: str = Field(description="Action to perform: 'get', 'start', 'pause' or 'skip'.")
      spotify_uri: Optional[str] = Field(default=None, description="Spotify uri of item to play for 'start' action. " +
                                                                   "If omitted, resumes current playback.")
      num_skips: Optional[int] = Field(default=1, description="Number of tracks to skip for `skip` action.")

• src/spotify_mcp/server.py:116-129 (registration)

  Registers the SpotifyPlayback tool (as Playback.as_tool()) in the MCP server's list_tools handler, constructing name as 'SpotifyPlayback'.

  @server.list_tools()
  async def handle_list_tools() -> list[types.Tool]:
      """List available tools."""
      logger.info("Listing available tools")
      # await server.request_context.session.send_notification("are you recieving this notification?")
      tools = [
          Playback.as_tool(),
          Search.as_tool(),
          Queue.as_tool(),
          GetInfo.as_tool(),
          Playlist.as_tool(),
      ]
      logger.info(f"Available tools: {[tool.name for tool in tools]}")
      return tools

• src/spotify_mcp/server.py:141-182 (handler)

  Main handler logic for SpotifyPlayback tool within the @server.call_tool() function. Dispatches based on 'action' to spotify_client methods: get_current_track, start_playback, pause_playback, skip_track.

  case "Playback":
      action = arguments.get("action")
      match action:
          case "get":
              logger.info("Attempting to get current track")
              curr_track = spotify_client.get_current_track()
              if curr_track:
                  logger.info(f"Current track retrieved: {curr_track.get('name', 'Unknown')}")
                  return [types.TextContent(
                      type="text",
                      text=json.dumps(curr_track, indent=2)
                  )]
              logger.info("No track currently playing")
              return [types.TextContent(
                  type="text",
                  text="No track playing."
              )]
          case "start":
              logger.info(f"Starting playback with arguments: {arguments}")
              spotify_client.start_playback(spotify_uri=arguments.get("spotify_uri"))
              logger.info("Playback started successfully")
              return [types.TextContent(
                  type="text",
                  text="Playback starting."
              )]
          case "pause":
              logger.info("Attempting to pause playback")
              spotify_client.pause_playback()
              logger.info("Playback paused successfully")
              return [types.TextContent(
                  type="text",
                  text="Playback paused."
              )]
          case "skip":
              num_skips = int(arguments.get("num_skips", 1))
              logger.info(f"Skipping {num_skips} tracks.")
              spotify_client.skip_track(n=num_skips)
              return [types.TextContent(
                  type="text",
                  text="Skipped to next track."
              )]

• src/spotify_mcp/spotify_api.py:114-136 (helper)

  Helper method spotify_client.get_current_track() called by handler for 'get' action.

  def get_current_track(self) -> Optional[Dict]:
      """Get information about the currently playing track"""
      try:
          # current_playback vs current_user_playing_track?
          current = self.sp.current_user_playing_track()
          if not current:
              self.logger.info("No playback session found")
              return None
          if current.get('currently_playing_type') != 'track':
              self.logger.info("Current playback is not a track")
              return None
  
          track_info = utils.parse_track(current['item'])
          if 'is_playing' in current:
              track_info['is_playing'] = current['is_playing']
  
          self.logger.info(
              f"Current track: {track_info.get('name', 'Unknown')} by {track_info.get('artist', 'Unknown')}")
          return track_info
      except Exception as e:
          self.logger.error("Error getting current track info.")
          raise

• src/spotify_mcp/spotify_api.py:138-172 (helper)

  Helper method spotify_client.start_playback() called by handler for 'start' action.

  def start_playback(self, spotify_uri=None, device=None):
      """
      Starts spotify playback of uri. If spotify_uri is omitted, resumes current playback.
      - spotify_uri: ID of resource to play, or None. Typically looks like 'spotify:track:xxxxxx' or 'spotify:album:xxxxxx'.
      """
      try:
          self.logger.info(f"Starting playback for spotify_uri: {spotify_uri} on {device}")
          if not spotify_uri:
              if self.is_track_playing():
                  self.logger.info("No track_id provided and playback already active.")
                  return
              if not self.get_current_track():
                  raise ValueError("No track_id provided and no current playback to resume.")
  
          if spotify_uri is not None:
              if spotify_uri.startswith('spotify:track:'):
                  uris = [spotify_uri]
                  context_uri = None
              else:
                  uris = None
                  context_uri = spotify_uri
          else:
              uris = None
              context_uri = None
  
          device_id = device.get('id') if device else None
  
          self.logger.info(f"Starting playback of on {device}: context_uri={context_uri}, uris={uris}")
          result = self.sp.start_playback(uris=uris, context_uri=context_uri, device_id=device_id)
          self.logger.info(f"Playback result: {result}")
          return result
      except Exception as e:
          self.logger.error(f"Error starting playback: {str(e)}.")
          raise