search_tracks
Search for Spotify tracks, albums, artists, or playlists using a query, type, and result limit. Simplifies finding music content on Spotify via the MCP server.
Instructions
Search Spotify for tracks, albums, artists, or playlists.
Args:
query: Search query
qtype: Type ('track', 'album', 'artist', 'playlist')
limit: Max results
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| qtype | No | track | |
| query | Yes |
Implementation Reference
- The primary handler function for the 'search_tracks' tool, including @mcp.tool() decorator for FastMCP registration. Executes Spotify search API, parses results into Track objects, handles qtype variations, validates limits, supports pagination with offset/limit, and returns structured results with metadata.@log_tool_execution def search_tracks( query: str, qtype: str = "track", limit: int = 10, offset: int = 0 ) -> dict[str, Any]: """Search Spotify for tracks, albums, artists, or playlists. Args: query: Search query qtype: Type ('track', 'album', 'artist', 'playlist') limit: Max results per page (1-50, default 10) offset: Number of results to skip for pagination (default 0) Returns: Dict with 'items' (list of tracks) and pagination info ('total', 'limit', 'offset') Note: For large result sets, use offset to paginate through results. Example: offset=0 gets results 1-10, offset=10 gets results 11-20, etc. """ try: # Validate limit (Spotify API accepts 1-50) limit = max(1, min(50, limit)) logger.info( f"🔍 Searching {qtype}s: '{query}' (limit={limit}, offset={offset})" ) result = spotify_client.search(q=query, type=qtype, limit=limit, offset=offset) tracks = [] items_key = f"{qtype}s" result_section = result.get(items_key, {}) if qtype == "track" and result_section.get("items"): tracks = [parse_track(item) for item in result_section["items"]] else: # Convert other types to track-like format for consistency if result_section.get("items"): for item in result_section["items"]: track = Track( name=item["name"], id=item["id"], artist=item.get("artists", [{}])[0].get("name", "Unknown") if qtype != "artist" else item["name"], external_urls=item.get("external_urls"), ) tracks.append(track) total_results = result_section.get("total", 0) logger.info( f"🔍 Search returned {len(tracks)} items (total available: {total_results})" ) log_pagination_info("search_tracks", total_results, limit, offset) return { "items": tracks, "total": total_results, "limit": result_section.get("limit", limit), "offset": result_section.get("offset", offset), "next": result_section.get("next"), "previous": result_section.get("previous"), } except SpotifyException as e: raise convert_spotify_error(e) from e
- Pydantic BaseModel defining the output schema for Track objects returned in search_tracks 'items' list. Used for structured serialization of search results.class Track(BaseModel): """A Spotify track with metadata.""" name: str id: str artist: str artists: list[str] | None = None album: str | None = None duration_ms: int | None = None popularity: int | None = None external_urls: dict[str, str] | None = None
- Utility function to parse raw Spotify track dictionary into structured Track model instance. Called within search_tracks to process search results.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"), )