Spotify MCP Server

Instructions

Implementation Reference

• src/spotify_mcp/spotify_api.py:58-72 (handler)

  Core implementation of the Spotify search functionality, calling spotipy.search and parsing results with utils.parse_search_results.
  def search(self, query: str, qtype: str = 'track', limit=10, device=None): """ 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 """ if self.username is None: self.set_username() results = self.sp.search(q=query, limit=limit, type=qtype) if not results: raise ValueError("No search results found.") return utils.parse_search_results(results, qtype, self.username)
• src/spotify_mcp/server.py:183-194 (handler)

  Tool dispatcher handler case for 'SpotifySearch', invokes spotify_client.search with parsed arguments and returns JSON 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:79-86 (schema)

  Pydantic schema defining the input parameters 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:116-129 (registration)

  Registers the SpotifySearch tool (as 'SpotifySearch') by including Search.as_tool() in the list of available tools.
  @server.list_tools() async def handle_list_tools() -> list[types.Tool]: """List available tools.""" logger.info("Listing available tools") # await server.request_context.session.send_notification("are you recieving this notification?") tools = [ Playback.as_tool(), Search.as_tool(), Queue.as_tool(), GetInfo.as_tool(), Playlist.as_tool(), ] logger.info(f"Available tools: {[tool.name for tool in tools]}") return tools
• src/spotify_mcp/utils.py:118-146 (helper)

  Helper function to parse and structure search results from spotipy into a standardized dictionary format.
  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)