SpotifySearch
Search for tracks, albums, artists, or playlists on Spotify using specific search terms and filters to find music content.
Instructions
Search for tracks, albums, artists, or playlists on Spotify.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of items to return | |
| qtype | No | Type of items to search for (track, album, artist, playlist, or comma-separated combination) | track |
| query | Yes | query term |
Implementation Reference
- src/spotify_mcp/server.py:163-175 (handler)Handler logic for executing the SpotifySearch tool: extracts arguments, calls spotify_client.search, and returns JSON-formatted results.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/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 (via Search.as_tool()) in the MCP server's tool list.@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/spotify_api.py:47-57 (helper)SpotifyClient.search method: performs the actual Spotify API search using spotipy and parses results.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)Utility function to parse and structure raw search results from Spotify API by type.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)