Spotify MCP Server

Instructions

Args:
    action: Action ('get', 'start', 'pause', 'skip')
    track_id: Track ID to play (for 'start')
    num_skips: Number of tracks to skip

Implementation Reference

• src/spotify_mcp/fastmcp_server.py:212-269 (handler)

  The playback_control tool handler: controls Spotify playback with actions 'get', 'start', 'pause', 'skip'. Includes registration via @mcp.tool() decorator.

  @mcp.tool()
  @log_tool_execution
  def playback_control(
      action: str, track_id: str | None = None, num_skips: int = 1
  ) -> PlaybackState:
      """Control Spotify playback.
  
      Args:
          action: Action ('get', 'start', 'pause', 'skip')
          track_id: Track ID to play (for 'start')
          num_skips: Number of tracks to skip
      """
      try:
          if action == "get":
              logger.info("🎵 Getting current playback state")
              result = spotify_client.current_user_playing_track()
          elif action == "start":
              if track_id:
                  logger.info(f"🎵 Starting playback of track: {track_id}")
                  spotify_client.start_playback(uris=[f"spotify:track:{track_id}"])
              else:
                  logger.info("🎵 Resuming playback")
                  spotify_client.start_playback()
              result = spotify_client.current_user_playing_track()
          elif action == "pause":
              logger.info("🎵 Pausing playback")
              spotify_client.pause_playback()
              result = spotify_client.current_user_playing_track()
          elif action == "skip":
              logger.info(f"🎵 Skipping {num_skips} track(s)")
              for _ in range(num_skips):
                  spotify_client.next_track()
              result = spotify_client.current_user_playing_track()
          else:
              raise ValueError(f"Invalid action: {action}")
  
          # Parse result
          track = None
          if result and result.get("item"):
              track = parse_track(result["item"])
  
          return PlaybackState(
              is_playing=result.get("is_playing", False) if result else False,
              track=track,
              device=result.get("device", {}).get("name")
              if result and result.get("device")
              else None,
              volume=result.get("device", {}).get("volume_percent")
              if result and result.get("device")
              else None,
              shuffle=result.get("shuffle_state", False) if result else False,
              repeat=result.get("repeat_state", "off") if result else "off",
              progress_ms=result.get("progress_ms") if result else None,
          )
  
      except SpotifyException as e:
          raise convert_spotify_error(e) from e

• src/spotify_mcp/fastmcp_server.py:55-64 (schema)

  Pydantic schema model PlaybackState used as return type for the tool.

  class PlaybackState(BaseModel):
      """Current playback state."""
  
      is_playing: bool
      track: Track | None = None
      device: str | None = None
      volume: int | None = None
      shuffle: bool = False
      repeat: str = "off"
      progress_ms: int | None = None

• src/spotify_mcp/fastmcp_server.py:40-52 (schema)

  Pydantic schema model Track used within PlaybackState.

  class Track(BaseModel):
      """A Spotify track with metadata."""
  
      name: str
      id: str
      artist: str
      artists: list[str] | None = None
      album: str | None = None
      album_id: str | None = None
      release_date: str | None = None
      duration_ms: int | None = None
      popularity: int | None = None
      external_urls: dict[str, str] | None = None

• src/spotify_mcp/fastmcp_server.py:124-138 (helper)

  Helper function parse_track to convert Spotify API track data to Track model, used in playback_control.

  def parse_track(item: dict[str, Any]) -> Track:
      """Parse Spotify track data into Track model."""
      album_data = item.get("album", {})
      return Track(
          name=item["name"],
          id=item["id"],
          artist=item["artists"][0]["name"] if item.get("artists") else "Unknown",
          artists=[a["name"] for a in item.get("artists", [])],
          album=album_data.get("name"),
          album_id=album_data.get("id"),
          release_date=album_data.get("release_date"),
          duration_ms=item.get("duration_ms"),
          popularity=item.get("popularity"),
          external_urls=item.get("external_urls"),
      )