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

Implementation Reference

src/spotify_mcp/fastmcp_server.py:575-623 (handler)

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

src/spotify_mcp/fastmcp_server.py:67-77 (schema)

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()
```
src/spotify_mcp/fastmcp_server.py:16-17 (helper)
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,
```

Spotify MCP Server