Spotify MCP Server

Instructions

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'

Implementation Reference

• src/spotify_mcp/fastmcp_server.py:879-942 (handler)

  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()

• src/spotify_mcp/fastmcp_server.py:40-52 (schema)

  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