SpotifySearch
Search Spotify for tracks, albums, artists, or playlists using query terms and filters to find specific music content.
Instructions
Search for tracks, albums, artists, or playlists on Spotify.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | query term | |
| qtype | No | Type of items to search for (track, album, artist, playlist, or comma-separated combination) | track |
| limit | No | Maximum number of items to return |
Implementation Reference
- src/spotify_mcp/server.py:90-95 (schema)Pydantic model defining the input schema for the SpotifySearch tool.
class Search(ToolModel): """Search for tracks, albums, artists, or playlists on Spotify.""" query: str = Field(description="query term") qtype: Optional[str] = Field(default="track", description="Type of items to search for (track, album, artist, playlist, or comma-separated combination)") limit: Optional[int] = Field(default=10, description="Maximum number of items to return") - src/spotify_mcp/server.py:97-108 (registration)Registers the SpotifySearch tool by including it in the list returned by list_tools().
@server.list_tools() async def handle_list_tools() -> list[types.Tool]: """List available tools.""" logger.info("Listing available tools") tools = [ Playback.as_tool(), Search.as_tool(), Queue.as_tool(), GetInfo.as_tool(), ] logger.info(f"Available tools: {[tool.name for tool in tools]}") return tools - src/spotify_mcp/server.py:163-175 (handler)MCP handler for SpotifySearch: parses arguments, calls Spotify client search, and returns results as JSON.
case "Search": logger.info(f"Performing search with arguments: {arguments}") search_results = spotify_client.search( query=arguments.get("query", ""), qtype=arguments.get("qtype", "track"), limit=arguments.get("limit", 10) ) logger.info("Search completed successfully") return [types.TextContent( type="text", text=json.dumps(search_results, indent=2) )] - src/spotify_mcp/spotify_api.py:47-57 (handler)Core implementation of the search functionality using Spotipy client.
def search(self, query: str, qtype: str = 'track', limit=10): """ Searches based of query term. - query: query term - qtype: the types of items to return. One or more of 'artist', 'album', 'track', 'playlist'. If multiple types are desired, pass in a comma separated string; e.g. 'track,album' - limit: max # items to return """ results = self.sp.search(q=query, limit=limit, type=qtype) return utils.parse_search_results(results, qtype) - src/spotify_mcp/utils.py:99-124 (helper)Helper function to parse and format Spotify search results into a structured dictionary.
def parse_search_results(results: Dict, qtype: str): _results = defaultdict(list) for q in qtype.split(","): match q: case "track": for idx, item in enumerate(results['tracks']['items']): if not item: continue _results['tracks'].append(parse_track(item)) case "artist": for idx, item in enumerate(results['artists']['items']): if not item: continue _results['artists'].append(parse_artist(item)) case "playlist": for idx, item in enumerate(results['playlists']['items']): if not item: continue _results['playlists'].append(parse_playlist(item)) case "album": for idx, item in enumerate(results['albums']['items']): if not item: continue _results['albums'].append(parse_album(item)) case _: raise ValueError(f"uknown qtype {qtype}") return dict(_results)