Spotify MCP Server

Instructions

Implementation Reference

• src/spotify_mcp/spotify_api.py:64-97 (handler)

  Core handler function that implements the logic for retrieving and parsing detailed information about a Spotify item based on its ID and type (track, album, artist, or playlist).
  def get_info(self, item_id: str, qtype: str = 'track') -> dict: """ Returns more info about item. - item_id: id. - qtype: Either 'track', 'album', 'artist', or 'playlist'. """ match qtype: case 'track': return utils.parse_track(self.sp.track(item_id), detailed=True) case 'album': album_info = utils.parse_album(self.sp.album(item_id), detailed=True) return album_info case 'artist': artist_info = utils.parse_artist(self.sp.artist(item_id), detailed=True) albums = self.sp.artist_albums(item_id) top_tracks = self.sp.artist_top_tracks(item_id)['tracks'] albums_and_tracks = { 'albums': albums, 'tracks': {'items': top_tracks} } parsed_info = utils.parse_search_results(albums_and_tracks, qtype="album,track") artist_info['top_tracks'] = parsed_info['tracks'] artist_info['albums'] = parsed_info['albums'] return artist_info case 'playlist': playlist = self.sp.playlist(item_id) playlist_info = utils.parse_playlist(playlist, detailed=True) return playlist_info raise ValueError(f"uknown qtype {qtype}")
• src/spotify_mcp/server.py:82-88 (schema)

  Pydantic model defining the input schema for the SpotifyGetInfo tool, including item_id and qtype parameters.
  class GetInfo(ToolModel): """Get detailed information about a Spotify item (track, album, artist, or playlist).""" item_id: str = Field(description="ID of the item to get information about") qtype: str = Field(default="track", description="Type of item: 'track', 'album', 'artist', or 'playlist'. " "If 'playlist' or 'album', returns its tracks. If 'artist'," "returns albums and top tracks.")
• src/spotify_mcp/server.py:97-108 (registration)

  Registers the SpotifyGetInfo tool (as 'SpotifyGetInfo') by including it in the list returned by the list_tools handler.
  @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:209-218 (handler)

  Dispatch handler in the main call_tool function that invokes the Spotify client get_info method with parsed arguments and formats the response.
  case "GetInfo": logger.info(f"Getting item info with arguments: {arguments}") item_info = spotify_client.get_info( item_id=arguments.get("item_id"), qtype=arguments.get("qtype", "track") ) return [types.TextContent( type="text", text=json.dumps(item_info, indent=2) )]
• src/spotify_mcp/utils.py:11-40 (helper)

  Helper function used by get_info to parse track details, extracting and formatting key fields like name, id, artists, album, etc.
  def parse_track(track_item: dict, detailed=False) -> Optional[dict]: if not track_item: return None narrowed_item = { 'name': track_item['name'], 'id': track_item['id'], } if 'is_playing' in track_item: narrowed_item['is_playing'] = track_item['is_playing'] if detailed: narrowed_item['album'] = parse_album(track_item.get('album')) for k in ['track_number', 'duration_ms']: narrowed_item[k] = track_item.get(k) if not track_item.get('is_playable', True): narrowed_item['is_playable'] = False artists = [a['name'] for a in track_item['artists']] if detailed: artists = [parse_artist(a) for a in track_item['artists']] if len(artists) == 1: narrowed_item['artist'] = artists[0] else: narrowed_item['artists'] = artists return narrowed_item