spotify_find_similar_tracks

Instructions

Centerpiece of the similarity engine. Supports 8 strategies, custom weighting, and automated
playlist creation. For curated playlists, music discovery, and mood-based mixes.

Args:
    Source (one required): track_id, artist_id, or playlist_id

    Strategy (default: euclidean): euclidean, weighted (needs weights), cosine, manhattan,
    energy_match (workout), mood_match (relaxation), rhythm_match (running), genre_match (non-catalog scope only)

    Scope (default: catalog): catalog (recommendations API), playlist (needs scope_id),
    artist (needs scope_id), album (needs scope_id), saved_tracks

    Action (default: return_tracks): return_tracks, create_playlist (needs playlist_name),
    add_to_playlist (needs target_playlist_id)

    - limit: Results to return, 1-100 (default: 20)
    - min_similarity: Optional threshold, 0.0-1.0
    - weights: Optional custom weights for 'weighted' strategy (e.g., {"energy": 5.0, "danceability": 5.0})
    - response_format: 'markdown' or 'json'

Returns:
    return_tracks: List with similarity scores (Markdown or JSON: {"strategy": "...", "scope": "...", "count": N, "tracks": [{track, similarity}]})
    create_playlist: {"success": true, "action": "create_playlist", "playlist_id": "...", "playlist_name": "...", "playlist_url": "...", "tracks_added": N, "message": "..."}
    add_to_playlist: {"success": true, "action": "add_to_playlist", "playlist_id": "...", "tracks_added": N, "message": "..."}

Examples:
    - "Find songs similar to this track" -> track_id, catalog scope
    - "Create workout playlist like this" -> track_id, energy_match, create_playlist
    - "Filter playlist by genre" -> track_id, genre_match, playlist scope
    - "Custom similarity for energy/dance" -> weighted strategy, custom weights

Errors: Returns errors for missing source, missing scope_id, missing action params, genre_match with catalog, no genres, no matches, auth (401), permissions (403), rate limits (429).

Implementation Reference

• server.py:658-667 (registration)

  Registration of the tool 'spotify_find_similar_tracks' using the @mcp.tool decorator.

  @mcp.tool(
      name="spotify_find_similar_tracks",
      annotations={
          "title": "Find Similar Tracks Using Audio Features",
          "readOnlyHint": False,  # Can create playlists
          "destructiveHint": False,
          "idempotentHint": False,
          "openWorldHint": True,
      },
  )

• server.py:668-924 (handler)

  The core handler function that orchestrates similarity search: validates inputs, fetches source features or genres, retrieves candidate tracks from specified scope, computes similarity scores using selected strategy, filters/sorts results, and executes actions (return, create playlist, or add to playlist). Delegates to helper functions for computations.

  async def spotify_find_similar_tracks(params: FindSimilarTracksInput) -> str:
      """Find tracks similar to a track, artist, or playlist using audio analysis or genre matching.
  
      Centerpiece of the similarity engine. Supports 8 strategies, custom weighting, and automated
      playlist creation. For curated playlists, music discovery, and mood-based mixes.
  
      Args:
          Source (one required): track_id, artist_id, or playlist_id
  
          Strategy (default: euclidean): euclidean, weighted (needs weights), cosine, manhattan,
          energy_match (workout), mood_match (relaxation), rhythm_match (running), genre_match (non-catalog scope only)
  
          Scope (default: catalog): catalog (recommendations API), playlist (needs scope_id),
          artist (needs scope_id), album (needs scope_id), saved_tracks
  
          Action (default: return_tracks): return_tracks, create_playlist (needs playlist_name),
          add_to_playlist (needs target_playlist_id)
  
          - limit: Results to return, 1-100 (default: 20)
          - min_similarity: Optional threshold, 0.0-1.0
          - weights: Optional custom weights for 'weighted' strategy (e.g., {"energy": 5.0, "danceability": 5.0})
          - response_format: 'markdown' or 'json'
  
      Returns:
          return_tracks: List with similarity scores (Markdown or JSON: {"strategy": "...", "scope": "...", "count": N, "tracks": [{track, similarity}]})
          create_playlist: {"success": true, "action": "create_playlist", "playlist_id": "...", "playlist_name": "...", "playlist_url": "...", "tracks_added": N, "message": "..."}
          add_to_playlist: {"success": true, "action": "add_to_playlist", "playlist_id": "...", "tracks_added": N, "message": "..."}
  
      Examples:
          - "Find songs similar to this track" -> track_id, catalog scope
          - "Create workout playlist like this" -> track_id, energy_match, create_playlist
          - "Filter playlist by genre" -> track_id, genre_match, playlist scope
          - "Custom similarity for energy/dance" -> weighted strategy, custom weights
  
      Errors: Returns errors for missing source, missing scope_id, missing action params, genre_match with catalog, no genres, no matches, auth (401), permissions (403), rate limits (429).
      """
      try:
          # Validate source
          if not params.track_id and not params.artist_id and not params.playlist_id:
              return "Error: At least one of track_id, artist_id, or playlist_id must be provided."
  
          # Validate scope_id for non-catalog scopes
          if params.scope != SearchScope.CATALOG and not params.scope_id:
              return f"Error: scope_id is required for scope '{params.scope.value}'"
  
          # Validate action parameters
          if (
              params.action == SimilarityAction.CREATE_PLAYLIST
              and not params.playlist_name
          ):
              return "Error: playlist_name is required for 'create_playlist' action"
          if (
              params.action == SimilarityAction.ADD_TO_PLAYLIST
              and not params.target_playlist_id
          ):
              return "Error: target_playlist_id is required for 'add_to_playlist' action"
  
          similar_tracks = []
  
          # Handle GENRE_MATCH strategy separately (uses artist genres instead of audio features)
          if params.strategy == SimilarityStrategy.GENRE_MATCH:
              # Genre matching requires a specific scope (not catalog)
              if params.scope == SearchScope.CATALOG:
                  return "Error: GENRE_MATCH strategy requires a specific scope (playlist, artist, album, or saved_tracks), not catalog"
  
              # Get source genres
              source_genres = await get_source_genres(
                  params.track_id, params.artist_id, params.playlist_id
              )
  
              if not source_genres:
                  return "Error: No genres found for the source track/artist/playlist"
  
              # Get candidate tracks from specified scope
              candidate_tracks = await get_candidate_tracks(
                  params.scope, params.scope_id, limit=500
              )
  
              # Calculate genre similarity for each track
              for track in candidate_tracks:
                  # Get genres for this track
                  target_genres = await get_track_genres(track)
  
                  if target_genres:
                      similarity = calculate_genre_similarity(
                          source_genres, target_genres
                      )
  
                      # Apply minimum similarity filter
                      if (
                          params.min_similarity is None
                          or similarity >= params.min_similarity
                      ):
                          similar_tracks.append(
                              {
                                  "track": track,
                                  "similarity": similarity,
                                  "genres": target_genres,
                              }
                          )
  
          else:
              # Audio feature-based matching
              # Get source audio features
              source_features = await get_source_features(
                  params.track_id, params.artist_id, params.playlist_id
              )
  
              if params.scope == SearchScope.CATALOG:
                  # Use recommendations API for catalog search
                  seed_params = {}
                  if params.track_id:
                      seed_params["seed_tracks"] = params.track_id
                  elif params.artist_id:
                      seed_params["seed_artists"] = params.artist_id
  
                  # Use source features as targets for recommendations
                  seed_params["limit"] = params.limit
                  seed_params["target_acousticness"] = source_features.get("acousticness")
                  seed_params["target_danceability"] = source_features.get("danceability")
                  seed_params["target_energy"] = source_features.get("energy")
                  seed_params["target_instrumentalness"] = source_features.get(
                      "instrumentalness"
                  )
                  seed_params["target_valence"] = source_features.get("valence")
                  seed_params["target_tempo"] = source_features.get("tempo")
  
                  data = await make_spotify_request("recommendations", params=seed_params)
                  candidate_tracks = data.get("tracks", [])
  
              else:
                  # Get candidate tracks from specified scope
                  candidate_tracks = await get_candidate_tracks(
                      params.scope, params.scope_id, limit=500
                  )
  
              # Get audio features for candidate tracks
              candidate_ids = [track["id"] for track in candidate_tracks]
              features_map = await get_audio_features_for_tracks(candidate_ids)
  
              # Calculate similarity scores
              for track in candidate_tracks:
                  track_id = track["id"]
                  if track_id in features_map:
                      target_features = features_map[track_id]
                      similarity = calculate_similarity(
                          source_features,
                          target_features,
                          params.strategy,
                          params.weights,
                      )
  
                      # Apply minimum similarity filter
                      if (
                          params.min_similarity is None
                          or similarity >= params.min_similarity
                      ):
                          similar_tracks.append(
                              {
                                  "track": track,
                                  "similarity": similarity,
                                  "features": target_features,
                              }
                          )
  
          # Sort by similarity (descending for similarity scores)
          similar_tracks.sort(key=lambda x: x["similarity"], reverse=True)
  
          # Limit results
          similar_tracks = similar_tracks[: params.limit]
  
          if not similar_tracks:
              return "No similar tracks found matching the criteria."
  
          # Execute action
          if params.action == SimilarityAction.CREATE_PLAYLIST:
              # Create new playlist with similar tracks
              playlist_data = await create_playlist_helper(
                  name=params.playlist_name,
                  description=f"Similar tracks found using {params.strategy.value} strategy",
                  public=False,
              )
  
              # Add tracks to playlist
              track_uris = [item["track"]["uri"] for item in similar_tracks]
              await add_tracks_to_playlist_helper(
                  playlist_id=playlist_data["id"],
                  track_uris=track_uris,
              )
  
              return json.dumps(
                  {
                      "success": True,
                      "action": "create_playlist",
                      "playlist_id": playlist_data["id"],
                      "playlist_name": playlist_data["name"],
                      "playlist_url": playlist_data["external_urls"]["spotify"],
                      "tracks_added": len(track_uris),
                      "message": f"Created playlist '{params.playlist_name}' with {len(track_uris)} similar tracks",
                  },
                  indent=2,
              )
  
          elif params.action == SimilarityAction.ADD_TO_PLAYLIST:
              # Add tracks to existing playlist
              track_uris = [item["track"]["uri"] for item in similar_tracks]
              await add_tracks_to_playlist_helper(
                  playlist_id=params.target_playlist_id,
                  track_uris=track_uris,
              )
  
              return json.dumps(
                  {
                      "success": True,
                      "action": "add_to_playlist",
                      "playlist_id": params.target_playlist_id,
                      "tracks_added": len(track_uris),
                      "message": f"Added {len(track_uris)} similar tracks to playlist",
                  },
                  indent=2,
              )
  
          else:
              # Return tracks
              if params.response_format == ResponseFormat.MARKDOWN:
                  lines = ["# Similar Tracks\n"]
                  lines.append(f"Strategy: {params.strategy.value}")
                  lines.append(f"Scope: {params.scope.value}")
                  lines.append(f"Found {len(similar_tracks)} similar tracks\n")
  
                  for i, item in enumerate(similar_tracks, 1):
                      track = item["track"]
                      similarity = item["similarity"]
                      lines.append(f"## {i}. {format_track_markdown(track)}")
                      lines.append(f"- **Similarity Score**: {similarity:.3f}\n")
  
                  return "\n".join(lines)
              else:
                  # JSON format
                  return json.dumps(
                      {
                          "strategy": params.strategy.value,
                          "scope": params.scope.value,
                          "count": len(similar_tracks),
                          "tracks": [
                              {
                                  "track": item["track"],
                                  "similarity": item["similarity"],
                              }
                              for item in similar_tracks
                          ],
                      },
                      indent=2,
                  )
  
      except Exception as e:
          return handle_spotify_error(e)

• spotify_mcp/types.py:223-312 (schema)

  Pydantic model defining the input schema for the spotify_find_similar_tracks tool, including source IDs, similarity strategy, search scope, limits, thresholds, actions for playlists, and output format with validation.

  class FindSimilarTracksInput(BaseModel):
      """Input model for finding similar tracks."""
  
      model_config = ConfigDict(str_strip_whitespace=True, validate_assignment=True)
  
      # Source track/entity
      track_id: str | None = Field(
          default=None,
          description="Spotify track ID to find similar tracks for",
      )
      artist_id: str | None = Field(
          default=None,
          description="Spotify artist ID to analyze their style",
      )
      playlist_id: str | None = Field(
          default=None,
          description="Playlist ID to analyze (uses average features of first 20 tracks)",
      )
  
      # Similarity configuration
      strategy: SimilarityStrategy = Field(
          default=SimilarityStrategy.EUCLIDEAN,
          description=(
              "Similarity algorithm: 'euclidean' (overall similarity), "
              "'weighted' (custom feature weights), 'cosine' (angular similarity), "
              "'manhattan' (city-block distance), 'energy_match' (energy/danceability focus), "
              "'mood_match' (valence/acousticness focus), 'rhythm_match' (tempo/time_signature focus), "
              "'genre_match' (artist genre matching)"
          ),
      )
      weights: FeatureWeights | None = Field(
          default=None,
          description="Feature weights (only used with 'weighted' strategy)",
      )
  
      # Search scope
      scope: SearchScope = Field(
          default=SearchScope.CATALOG,
          description=(
              "Search scope: 'catalog' (recommendations API), 'playlist' (within playlist), "
              "'artist' (artist's tracks), 'album' (within album), 'saved_tracks' (user's library)"
          ),
      )
      scope_id: str | None = Field(
          default=None,
          description="ID for scope (playlist_id, artist_id, or album_id) - required for non-catalog scopes",
      )
  
      # Result configuration
      limit: int = Field(
          default=20,
          description="Number of similar tracks to return",
          ge=1,
          le=100,
      )
      min_similarity: float | None = Field(
          default=None,
          description="Minimum similarity score (0.0-1.0, lower = more similar for distance metrics)",
          ge=0.0,
          le=1.0,
      )
  
      # Action configuration
      action: SimilarityAction = Field(
          default=SimilarityAction.RETURN_TRACKS,
          description=(
              "Action: 'return_tracks' (just return list), 'create_playlist' (create new playlist), "
              "'add_to_playlist' (add to existing playlist)"
          ),
      )
      playlist_name: str | None = Field(
          default=None,
          description="Playlist name (required for 'create_playlist' action)",
      )
      target_playlist_id: str | None = Field(
          default=None,
          description="Target playlist ID (required for 'add_to_playlist' action)",
      )
  
      response_format: ResponseFormat = Field(
          default=ResponseFormat.MARKDOWN,
          description="Output format: 'markdown' or 'json'",
      )
  
      @field_validator("track_id", "artist_id", "playlist_id")
      @classmethod
      def validate_source(cls, v: str | None, info) -> str | None:
          """Validate at least one source is provided."""
          return v