Spotify MCP Server

Instructions

Implementation Reference

• src/spotify_mcp/server.py:244-319 (handler)

  Main handler logic for executing the SpotifySearch tool. Extracts query, qtype, limit from arguments, calls spotify_client.search(), formats the search results into a user-friendly list with URIs and details for tracks, artists, albums, playlists, handles no results and errors.
  case "Search": try: logger.info(f"Performing search with arguments: {arguments}") query = arguments.get("query", "") qtype = arguments.get("qtype", "track") limit = arguments.get("limit", 10) search_results = spotify_client.search( query=query, qtype=qtype, limit=limit ) logger.info(f"Search results: {search_results}") formatted_results = [f"🔍 Search Results for {qtype}s:"] # Map qtype to corresponding key in the response result_items = search_results.get(f"{qtype}s", []) if not result_items: return create_error_response(f"No {qtype}s found for your query.") for idx, item in enumerate(result_items, start=1): if qtype == "track": title = item.get("name", "Unknown Title") uri = f"spotify:track:{item.get('id', 'N/A')}" formatted_results.append(f"{idx}. \"{title}\" by {get_artist_string(item)}\n URI: {uri}") elif qtype == "artist": name = item.get("name", "Unknown Artist") uri = f"spotify:artist:{item.get('id', 'N/A')}" formatted_results.append(f"{idx}. 👤 {name}\n URI: {uri}") elif qtype == "album": title = item.get("name", "Unknown Album") uri = f"spotify:album:{item.get('id', 'N/A')}" formatted_results.append(f"{idx}. 💿 \"{title}\" by {get_artist_string(item)}\n URI: {uri}") elif qtype == "playlist": name = item.get("name", "Unknown Playlist") owner = item.get("owner", "Unknown Owner") is_owner = item.get("user_is_owner", False) total_tracks = item.get("total_tracks", "N/A") uri = f"spotify:playlist:{item.get('id', 'N/A')}" ownership_text = "✅ You own this playlist" if is_owner else "👤 Owned by someone else" formatted_results.append( f"{idx}. 📜 \"{name}\"\n" f" Owner: {owner} | Tracks: {total_tracks}\n" f" {ownership_text}\n" f" URI: {uri}" ) else: formatted_results.append(f"{idx}. Unsupported qtype: {qtype}") return [types.TextContent( type="text", text="\n".join(formatted_results) )] except Exception as e: logger.error(f"Search failed: {e}") return create_error_response(f"An error occurred during search: {str(e)}")
• src/spotify_mcp/server.py:79-86 (schema)

  Pydantic input schema for the SpotifySearch tool, defining required 'query' and optional 'qtype' (default 'track') and 'limit' (default 10). Used to generate the tool schema via ToolModel.as_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:120-125 (registration)

  Registration of the SpotifySearch tool in the MCP list_tools handler. Search.as_tool() creates the types.Tool with name="SpotifySearch", added to the list of available tools.
  Playback.as_tool(), Search.as_tool(), Queue.as_tool(), GetInfo.as_tool(), Playlist.as_tool(), ]
• src/spotify_mcp/spotify_api.py:36-70 (helper)

  Core search implementation in SpotifyClient.smart_search, called indirectly via search(). Performs optional local search, falls back to Spotify API search (self.sp.search), parses results with utils.parse_search_results, merges local results if available, deduplicates by ID.
  def smart_search( self, query: str, qtype: str = 'track', limit: int = 10, ) -> dict: try: local_resp = requests.get( LOCAL_SEARCH_URL, params={'q': query, 'type': qtype}, timeout=5 ) local_resp.raise_for_status() local_data = local_resp.json().get("documents", []) self.logger.info(local_data) except RequestException as e: self.logger.info(f"[local search failed] {e}") local_data = None self.logger.info("Falling back to online Spotify search") online_results = self.sp.search(q=query, type=qtype, limit=limit,market=SPOTIFY_COUNTRY) parsed_results = utils.parse_search_results(online_results, qtype, self.username) if local_data and isinstance(local_data, list) and len(local_data) > 0 and (qtype == "track" or qtype == "playlist"): self.logger.info("Loading local results") local_results = utils.parse_local_documents(local_data, qtype) if local_results: for key in local_results: all_items = local_results[key] + parsed_results.get(key, []) # Remove duplicates using dict keyed by 'id' deduped = {item['id']: item for item in all_items if 'id' in item} parsed_results[key] = list(deduped.values()) return parsed_results
• src/spotify_mcp/utils.py:163-191 (helper)

  Utility function parse_search_results used by smart_search to parse raw Spotify search API results into simplified dictionaries for tracks, artists, albums, playlists using helper parse_* functions.
  def parse_search_results(results: Dict, qtype: str, username: Optional[str] = None): _results = defaultdict(list) # potential # if username: # _results['User Spotify URI'] = username 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, username)) case "album": for idx, item in enumerate(results['albums']['items']): if not item: continue _results['albums'].append(parse_album(item)) case _: raise ValueError(f"Unknown qtype {qtype}") return dict(_results)