get_user_playlists
Retrieve your Spotify playlists with pagination support to manage large collections efficiently. Use limit and offset parameters to control results.
Instructions
Get current user's playlists with pagination support.
Args:
limit: Max playlists to return per page (1-50, default 20)
offset: Number of playlists to skip for pagination (default 0)
Returns:
Dict with 'items' (list of playlists) and pagination info ('total', 'limit', 'offset')
Note: For users with many playlists, use offset to paginate through results.
Example: offset=0 gets playlists 1-20, offset=20 gets playlists 21-40, etc.Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Implementation Reference
- Main handler function for the 'get_user_playlists' MCP tool. Registered via @mcp.tool() decorator. Implements pagination, logging, error handling, and structures response using Playlist model.
@mcp.tool() @log_tool_execution def get_user_playlists(limit: int = 20, offset: int = 0) -> dict[str, Any]: """Get current user's playlists with pagination support. Args: limit: Max playlists to return per page (1-50, default 20) offset: Number of playlists to skip for pagination (default 0) Returns: Dict with 'items' (list of playlists) and pagination info ('total', 'limit', 'offset') Note: For users with many playlists, use offset to paginate through results. Example: offset=0 gets playlists 1-20, offset=20 gets playlists 21-40, etc. """ try: # Validate limit (Spotify API accepts 1-50) limit = max(1, min(50, limit)) logger.info(f"đź“‹ Getting user playlists (limit={limit}, offset={offset})") result = spotify_client.current_user_playlists(limit=limit, offset=offset) # Log pagination info log_pagination_info("get_user_playlists", result.get("total", 0), limit, offset) playlists = [] for item in result.get("items", []): playlist = Playlist( name=item["name"], id=item["id"], owner=item.get("owner", {}).get("display_name"), description=item.get("description"), total_tracks=item.get("tracks", {}).get("total"), public=item.get("public"), ) playlists.append(playlist) return { "items": playlists, "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 playlist objects returned by get_user_playlists tool.
class Playlist(BaseModel): """A Spotify playlist.""" name: str id: str owner: str | None = None description: str | None = None tracks: list[Track] | None = None total_tracks: int | None = None public: bool | None = None - src/spotify_mcp/fastmcp_server.py:575-575 (registration)FastMCP @mcp.tool() decorator that automatically registers the get_user_playlists function as an MCP tool.
@mcp.tool() - Imports logging utilities used in get_user_playlists, including log_pagination_info called within the handler and @log_tool_execution decorator.
from spotify_mcp.logging_utils import ( log_pagination_info,