get_saved_tracks
Retrieve your saved Spotify tracks from the Liked Songs library with pagination controls for managing large collections.
Instructions
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 infoInput Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Implementation Reference
- 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 - 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 - 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"), ) - 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)