Spotify MCP Server

Instructions

Implementation Reference

• src/spotify_mcp/fastmcp_server.py:486-534 (handler)

  MCP tool handler function that fetches the current user's Spotify playlists using pagination. It uses the Playlist Pydantic model for structured output and handles errors.
  @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:65-75 (schema)

  Pydantic BaseModel defining the structure for Spotify playlist data returned by the 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:87-98 (helper)

  Helper function to parse raw Spotify track data into the Track Pydantic model, used indirectly in playlist processing.
  def parse_track(item: dict[str, Any]) -> Track: """Parse Spotify track data into Track model.""" 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=item.get("album", {}).get("name"), duration_ms=item.get("duration_ms"), popularity=item.get("popularity"), external_urls=item.get("external_urls"), )
• src/spotify_mcp/fastmcp_server.py:486-486 (registration)

  FastMCP decorator that registers the get_user_playlists function as an MCP tool.
  @mcp.tool()