spotify_get_user_playlists
Retrieve your Spotify playlists to browse, find specific ones, or get playlist IDs for further management operations.
Instructions
Get a list of the current user's Spotify playlists.
Retrieves all playlists owned by or followed by the authenticated user. Results are
paginated. Use to browse playlists or find playlist IDs.
Args:
- limit: Number of playlists to return, 1-50 (default: 20)
- offset: Starting position for pagination (default: 0)
- response_format: 'markdown' or 'json'
Returns:
Markdown: List with playlist name, ID, track count, public status, description, URL
JSON: {"total": N, "count": N, "offset": N, "playlists": [{id, name, description, public, collaborative, tracks, owner, external_urls}], "has_more": bool}
Examples:
- "Show me my playlists" -> List all user playlists
- "Find my workout playlist" -> Browse to find specific one
- Need playlist ID -> Get ID from the list
Errors: Returns "No playlists found." if none exist, or error for auth failure (401), missing scopes (403), rate limits (429).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
Input Schema (JSON Schema)
{
"properties": {
"params": {
"$ref": "#/$defs/GetUserPlaylistsInput"
}
},
"required": [
"params"
],
"type": "object"
}
Implementation Reference
- server.py:276-285 (registration)Tool registration decorator defining the tool name and annotations.@mcp.tool( name="spotify_get_user_playlists", annotations={ "title": "Get User's Spotify Playlists", "readOnlyHint": True, "destructiveHint": False, "idempotentHint": True, "openWorldHint": True, }, )
- server.py:286-358 (handler)The async handler function that implements the tool logic: fetches user playlists via Spotify API, handles pagination, and returns formatted markdown or JSON response.async def spotify_get_user_playlists(params: GetUserPlaylistsInput) -> str: """Get a list of the current user's Spotify playlists. Retrieves all playlists owned by or followed by the authenticated user. Results are paginated. Use to browse playlists or find playlist IDs. Args: - limit: Number of playlists to return, 1-50 (default: 20) - offset: Starting position for pagination (default: 0) - response_format: 'markdown' or 'json' Returns: Markdown: List with playlist name, ID, track count, public status, description, URL JSON: {"total": N, "count": N, "offset": N, "playlists": [{id, name, description, public, collaborative, tracks, owner, external_urls}], "has_more": bool} Examples: - "Show me my playlists" -> List all user playlists - "Find my workout playlist" -> Browse to find specific one - Need playlist ID -> Get ID from the list Errors: Returns "No playlists found." if none exist, or error for auth failure (401), missing scopes (403), rate limits (429). """ try: query_params = {"limit": params.limit, "offset": params.offset} data = await make_spotify_request("me/playlists", params=query_params) playlists = data.get("items", []) total = data.get("total", 0) if not playlists: return "No playlists found." # Format response if params.response_format == ResponseFormat.MARKDOWN: lines = [ "# Your Spotify Playlists\n", f"Showing {len(playlists)} of {total} playlists\n", ] for playlist in playlists: lines.append(f"## {playlist['name']}") lines.append(f"- Playlist ID: `{playlist['id']}`") lines.append(f"- Tracks: {playlist.get('tracks', {}).get('total', 0)}") lines.append(f"- Public: {playlist.get('public', False)}") if playlist.get("description"): lines.append(f"- Description: {playlist['description']}") lines.append(f"- URL: {playlist['external_urls']['spotify']}\n") has_more = total > params.offset + len(playlists) if has_more: next_offset = params.offset + len(playlists) lines.append( f"\n*More playlists available. Use offset={next_offset} to see more.*" ) return "\n".join(lines) else: # JSON format return json.dumps( { "total": total, "count": len(playlists), "offset": params.offset, "playlists": playlists, "has_more": total > params.offset + len(playlists), }, indent=2, ) except Exception as e: return handle_spotify_error(e)
- spotify_mcp/types.py:141-154 (schema)Pydantic BaseModel defining the input schema with fields for limit, offset, and response_format.class GetUserPlaylistsInput(BaseModel): """Input model for getting user playlists.""" model_config = ConfigDict(str_strip_whitespace=True, validate_assignment=True) limit: int | None = Field( default=20, description="Number of playlists to return", ge=1, le=50 ) offset: int | None = Field(default=0, description="Offset for pagination", ge=0) response_format: ResponseFormat = Field( default=ResponseFormat.MARKDOWN, description="Output format: 'markdown' or 'json'", )