Spotify MCP Server

Instructions

Args:
    limit: Max tracks to return per page (1-50, default 20)
    offset: Number of tracks to skip for pagination (default 0)

Returns:
    Dict with 'items' (list of tracks with added_at timestamp) and pagination info

Implementation Reference

• src/spotify_mcp/fastmcp_server.py:840-877 (handler)

  The primary handler function for the 'get_saved_tracks' tool. Decorated with @mcp.tool() for automatic registration and @log_tool_execution for logging. Fetches the user's saved (liked) tracks from the Spotify API using current_user_saved_tracks with pagination parameters (limit, offset). Parses each track using parse_track helper, adds 'added_at' timestamp, logs pagination info, and returns a structured dictionary with tracks list and pagination metadata.

  @mcp.tool()
  @log_tool_execution
  def get_saved_tracks(limit: int = 20, offset: int = 0) -> dict[str, Any]:
      """Get user's saved/liked tracks (Liked Songs library).
  
      Args:
          limit: Max tracks to return per page (1-50, default 20)
          offset: Number of tracks to skip for pagination (default 0)
  
      Returns:
          Dict with 'items' (list of tracks with added_at timestamp) and pagination info
      """
      try:
          limit = max(1, min(50, limit))
  
          logger.info(f"❤️ Getting saved tracks (limit={limit}, offset={offset})")
          result = spotify_client.current_user_saved_tracks(limit=limit, offset=offset)
  
          tracks = []
          for item in result.get("items", []):
              if item and item.get("track"):
                  track_data = parse_track(item["track"]).model_dump()
                  track_data["added_at"] = item.get("added_at")
                  tracks.append(track_data)
  
          log_pagination_info("get_saved_tracks", result.get("total", 0), limit, offset)
  
          return {
              "items": tracks,
              "total": result.get("total", 0),
              "limit": result.get("limit", limit),
              "offset": result.get("offset", offset),
              "next": result.get("next"),
              "previous": result.get("previous"),
          }
      except SpotifyException as e:
          raise convert_spotify_error(e) from e

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

  Pydantic model defining the structure of track objects returned in the 'items' list of get_saved_tracks response.

  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 that parses raw Spotify track dictionary into a structured Track Pydantic model, used within get_saved_tracks to process API response items.

  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"),
      )

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

  Call to log_pagination_info utility for logging pagination details specific to get_saved_tracks.

  log_pagination_info("get_saved_tracks", result.get("total", 0), limit, offset)