Spotify MCP Server

Instructions

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)