Spotify MCP Server

Instructions

Implementation Reference

• src/spotify_mcp/fastmcp_server.py:408-443 (handler)

  Core handler function that fetches detailed track information from Spotify API. Handles single track ID or batch of up to 50 IDs, uses parse_track helper, returns structured dict with Track data.
  def get_track_info(track_ids: str | list[str]) -> dict[str, Any]: """Get detailed information about one or more Spotify tracks. Args: track_ids: Single track ID or list of track IDs (up to 50) Returns: Dict with 'tracks' list containing track metadata including release_date. For single ID, returns {'tracks': [track]}. Note: Batch lookup is much more efficient - 50 tracks = 1 API call instead of 50. """ try: # Normalize to list ids = [track_ids] if isinstance(track_ids, str) else track_ids if len(ids) > 50: raise ValueError("Maximum 50 track IDs per request (Spotify API limit)") logger.info(f"🎵 Getting track info for {len(ids)} track(s)") if len(ids) == 1: result = spotify_client.track(ids[0]) tracks = [parse_track(result).model_dump()] else: result = spotify_client.tracks(ids) tracks = [ parse_track(item).model_dump() for item in result.get("tracks", []) if item ] return {"tracks": tracks} except SpotifyException as e: raise convert_spotify_error(e) from e
• src/spotify_mcp/fastmcp_server.py:406-407 (registration)

  FastMCP decorator that registers get_track_info as a tool with automatic schema generation from signature and docstring. Includes logging decorator.
  @mcp.tool() @log_tool_execution
• src/spotify_mcp/fastmcp_server.py:40-53 (schema)

  Pydantic BaseModel defining the structured output format for tracks returned by get_track_info.
  class Track(BaseModel): """A Spotify track with metadata.""" name: str id: str artist: str artists: list[str] | None = None album: str | None = None album_id: str | None = None release_date: str | None = None duration_ms: int | None = None popularity: int | None = None external_urls: dict[str, str] | None = None
• src/spotify_mcp/fastmcp_server.py:124-138 (helper)

  Utility function that converts raw Spotify API track dictionary into the structured Track Pydantic model used by the handler.
  def parse_track(item: dict[str, Any]) -> Track: """Parse Spotify track data into Track model.""" album_data = item.get("album", {}) return Track( name=item["name"], id=item["id"], artist=item["artists"][0]["name"] if item.get("artists") else "Unknown", artists=[a["name"] for a in item.get("artists", [])], album=album_data.get("name"), album_id=album_data.get("id"), release_date=album_data.get("release_date"), duration_ms=item.get("duration_ms"), popularity=item.get("popularity"), external_urls=item.get("external_urls"), )