spotify_search_tracks

Instructions

Searches Spotify's entire catalog using intelligent matching. Results ranked by relevance.

Args:
    - query: Search text, 1-200 chars (e.g., "Bohemian Rhapsody", "artist:Queen", "album:...", or keywords)
    - limit: Results to return, 1-50 (default: 20)
    - offset: Starting position for pagination (default: 0)
    - response_format: 'markdown' or 'json'

Returns:
    Markdown: Search results with track details (name, artists, album, duration, ID, URI, popularity)
    JSON: {"total": N, "count": N, "offset": N, "tracks": [{id, name, artists, album, duration_ms, popularity, uri, external_urls}], "has_more": bool}

Examples:
    - "Find Bohemian Rhapsody by Queen" -> query="Bohemian Rhapsody Queen"
    - "Search for songs by Taylor Swift" -> query="artist:Taylor Swift"
    - "Look for indie rock songs" -> query="indie rock"

Errors: Returns "No tracks found" if no results, or error for auth failure (401), rate limits (429). Truncates if exceeds character limit.

Implementation Reference

• server.py:440-534 (handler)

  The @mcp.tool decorator registers the spotify_search_tracks handler function, which implements the core logic: validates input, calls Spotify's search API via make_spotify_request, formats results in markdown or JSON, handles pagination, truncation, and errors.

  @mcp.tool(
      name="spotify_search_tracks",
      annotations={
          "title": "Search Spotify Tracks",
          "readOnlyHint": True,
          "destructiveHint": False,
          "idempotentHint": True,
          "openWorldHint": True,
      },
  )
  async def spotify_search_tracks(params: SearchTracksInput) -> str:
      """Search for tracks on Spotify by name, artist, album, or keywords.
  
      Searches Spotify's entire catalog using intelligent matching. Results ranked by relevance.
  
      Args:
          - query: Search text, 1-200 chars (e.g., "Bohemian Rhapsody", "artist:Queen", "album:...", or keywords)
          - limit: Results to return, 1-50 (default: 20)
          - offset: Starting position for pagination (default: 0)
          - response_format: 'markdown' or 'json'
  
      Returns:
          Markdown: Search results with track details (name, artists, album, duration, ID, URI, popularity)
          JSON: {"total": N, "count": N, "offset": N, "tracks": [{id, name, artists, album, duration_ms, popularity, uri, external_urls}], "has_more": bool}
  
      Examples:
          - "Find Bohemian Rhapsody by Queen" -> query="Bohemian Rhapsody Queen"
          - "Search for songs by Taylor Swift" -> query="artist:Taylor Swift"
          - "Look for indie rock songs" -> query="indie rock"
  
      Errors: Returns "No tracks found" if no results, or error for auth failure (401), rate limits (429). Truncates if exceeds character limit.
      """
      try:
          query_params = {
              "q": params.query,
              "type": "track",
              "limit": params.limit,
              "offset": params.offset,
          }
  
          data = await make_spotify_request("search", params=query_params)
  
          tracks = data.get("tracks", {}).get("items", [])
          total = data.get("tracks", {}).get("total", 0)
  
          if not tracks:
              return f"No tracks found matching '{params.query}'"
  
          # Format response
          if params.response_format == ResponseFormat.MARKDOWN:
              lines = [
                  f"# Search Results: '{params.query}'\n",
                  f"Found {total} tracks (showing {len(tracks)})\n",
              ]
  
              for i, track in enumerate(tracks, 1):
                  lines.append(f"## {i}. {format_track_markdown(track)}\n")
  
              has_more = total > params.offset + len(tracks)
              if has_more:
                  next_offset = params.offset + len(tracks)
                  lines.append(
                      f"\n*More results available. Use offset={next_offset} to see more.*"
                  )
  
              result = "\n".join(lines)
              truncation_msg = check_character_limit(result, tracks)
              if truncation_msg:
                  tracks = tracks[: len(tracks) // 2]
                  lines = [
                      f"# Search Results: '{params.query}'\n",
                      truncation_msg,
                      f"Found {total} tracks (showing {len(tracks)})\n",
                  ]
                  for i, track in enumerate(tracks, 1):
                      lines.append(f"## {i}. {format_track_markdown(track)}\n")
                  result = "\n".join(lines)
  
              return result
          else:
              # JSON format
              return json.dumps(
                  {
                      "total": total,
                      "count": len(tracks),
                      "offset": params.offset,
                      "tracks": tracks,
                      "has_more": total > params.offset + len(tracks),
                  },
                  indent=2,
              )
  
      except Exception as e:
          return handle_spotify_error(e)

• spotify_mcp/types.py:174-190 (schema)

  Pydantic model defining the input parameters for the spotify_search_tracks tool: required query (1-200 chars), optional limit (1-50), offset (>=0), and response_format.

  class SearchTracksInput(BaseModel):
      """Input model for searching tracks."""
  
      model_config = ConfigDict(str_strip_whitespace=True, validate_assignment=True)
  
      query: str = Field(
          ..., description="Search query for tracks", min_length=1, max_length=200
      )
      limit: int | None = Field(
          default=20, description="Number of results 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'",
      )