Spotify MCP Server

Instructions

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.

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"),
      )