get_recommendations
Generate personalized music recommendations using seed artists, tracks, or genres from Spotify. Input up to 5 seeds to receive tailored track suggestions for discovering new music.
Instructions
Get track recommendations based on seed artists, tracks, or genres.
Args:
seed_artists: List of artist IDs (up to 5 total seeds combined)
seed_tracks: List of track IDs (up to 5 total seeds combined)
seed_genres: List of genres (up to 5 total seeds combined)
limit: Number of recommendations to return (1-100, default 20)
Returns:
Dict with 'tracks' list of recommended tracks
Note: Total seeds (artists + tracks + genres) must be between 1 and 5.
Use search_tracks to find seed track/artist IDs, or common genres like:
'pop', 'rock', 'hip-hop', 'electronic', 'jazz', 'classical', 'r-n-b', 'country'Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| seed_artists | No | ||
| seed_tracks | No | ||
| seed_genres | No | ||
| limit | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Implementation Reference
- The handler function implementing the get_recommendations tool. Decorated with @mcp.tool() for FastMCP registration and @log_tool_execution. Calls Spotify's recommendations API, validates seeds (1-5 total), parses results using parse_track helper, and returns recommended tracks with seeds used.
@mcp.tool() @log_tool_execution def get_recommendations( seed_artists: list[str] | None = None, seed_tracks: list[str] | None = None, seed_genres: list[str] | None = None, limit: int = 20, ) -> dict[str, Any]: """Get track recommendations based on seed artists, tracks, or genres. Args: seed_artists: List of artist IDs (up to 5 total seeds combined) seed_tracks: List of track IDs (up to 5 total seeds combined) seed_genres: List of genres (up to 5 total seeds combined) limit: Number of recommendations to return (1-100, default 20) Returns: Dict with 'tracks' list of recommended tracks Note: Total seeds (artists + tracks + genres) must be between 1 and 5. Use search_tracks to find seed track/artist IDs, or common genres like: 'pop', 'rock', 'hip-hop', 'electronic', 'jazz', 'classical', 'r-n-b', 'country' """ try: # Validate seeds total_seeds = ( len(seed_artists or []) + len(seed_tracks or []) + len(seed_genres or []) ) if total_seeds == 0: raise ValueError("At least one seed (artist, track, or genre) is required") if total_seeds > 5: raise ValueError("Maximum 5 total seeds allowed (artists + tracks + genres)") limit = max(1, min(100, limit)) logger.info( f"🎲 Getting recommendations (artists={seed_artists}, " f"tracks={seed_tracks}, genres={seed_genres}, limit={limit})" ) result = spotify_client.recommendations( seed_artists=seed_artists, seed_tracks=seed_tracks, seed_genres=seed_genres, limit=limit, ) tracks = [] for item in result.get("tracks", []): if item: tracks.append(parse_track(item).model_dump()) return { "tracks": tracks, "seeds": { "artists": seed_artists or [], "tracks": seed_tracks or [], "genres": seed_genres or [], }, } except SpotifyException as e: raise convert_spotify_error(e) from e - src/spotify_mcp/fastmcp_server.py:879-879 (registration)The @mcp.tool() decorator registers the get_recommendations function as an MCP tool in FastMCP, which automatically generates input schema from type hints.
@mcp.tool() - Pydantic model Track used for parsing and structuring recommended track data in the output.
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