Spotify Playlist MCP Server

Instructions

Adds 1-100 tracks to a playlist. Tracks can be inserted at a specific position or
appended to the end. Playlist must be owned by user or be collaborative.

Args:
    - playlist_id: Spotify playlist ID (not URI)
    - track_uris: List of track URIs, 1-100 (format: "spotify:track:ID", not just IDs)
    - position: Optional 0-indexed position to insert (default: append to end)

Returns:
    JSON: {"success": true, "snapshot_id": "...", "tracks_added": N, "message": "..."}

Examples:
    - "Add this track to my playlist" -> track_uris=["spotify:track:ID"], playlist_id="..."
    - "Add 10 songs to workout mix" -> track_uris=[list of URIs]
    - "Insert at the beginning" -> position=0

Errors: Returns error for invalid playlist (404), no permission (403), auth failure (401), rate limits (429).

Implementation Reference

• server.py:234-274 (handler)

  The main asynchronous handler function for the 'spotify_add_tracks_to_playlist' tool. It validates input via Pydantic, calls the helper to interact with Spotify API, formats JSON response with success info, and handles errors.

  async def spotify_add_tracks_to_playlist(params: AddTracksToPlaylistInput) -> str:
      """Add tracks to an existing Spotify playlist.
  
      Adds 1-100 tracks to a playlist. Tracks can be inserted at a specific position or
      appended to the end. Playlist must be owned by user or be collaborative.
  
      Args:
          - playlist_id: Spotify playlist ID (not URI)
          - track_uris: List of track URIs, 1-100 (format: "spotify:track:ID", not just IDs)
          - position: Optional 0-indexed position to insert (default: append to end)
  
      Returns:
          JSON: {"success": true, "snapshot_id": "...", "tracks_added": N, "message": "..."}
  
      Examples:
          - "Add this track to my playlist" -> track_uris=["spotify:track:ID"], playlist_id="..."
          - "Add 10 songs to workout mix" -> track_uris=[list of URIs]
          - "Insert at the beginning" -> position=0
  
      Errors: Returns error for invalid playlist (404), no permission (403), auth failure (401), rate limits (429).
      """
      try:
          data = await add_tracks_to_playlist_helper(
              playlist_id=params.playlist_id,
              track_uris=params.track_uris,
              position=params.position,
          )
  
          return json.dumps(
              {
                  "success": True,
                  "snapshot_id": data.get("snapshot_id"),
                  "tracks_added": len(params.track_uris),
                  "message": f"Successfully added {len(params.track_uris)} track(s) to playlist",
              },
              indent=2,
          )
  
      except Exception as e:
          return handle_spotify_error(e)

• spotify_mcp/types.py:122-138 (schema)

  Pydantic BaseModel defining the input schema for the tool, with fields for playlist_id, track_uris (list 1-100), and optional position, including validation constraints.

  class AddTracksToPlaylistInput(BaseModel):
      """Input model for adding tracks to a playlist."""
  
      model_config = ConfigDict(str_strip_whitespace=True, validate_assignment=True)
  
      playlist_id: str = Field(
          ..., description="Spotify playlist ID", min_length=1, max_length=100
      )
      track_uris: list[str] = Field(
          ...,
          description="List of Spotify track URIs to add (e.g., ['spotify:track:4iV5W9uYEdYUVa79Axb7Rh'])",
          min_length=1,
          max_length=100,
      )
      position: int | None = Field(
          default=None, description="Position to insert tracks (0-indexed)", ge=0
      )

• server.py:224-233 (registration)

  The @mcp.tool decorator that registers the 'spotify_add_tracks_to_playlist' function as an MCP tool, specifying the name and operational hints.

  @mcp.tool(
      name="spotify_add_tracks_to_playlist",
      annotations={
          "title": "Add Tracks to Spotify Playlist",
          "readOnlyHint": False,
          "destructiveHint": False,
          "idempotentHint": False,
          "openWorldHint": True,
      },
  )

• spotify_mcp/utils.py:251-277 (helper)

  Helper utility that makes the actual HTTP POST request to Spotify's API endpoint for adding tracks to a playlist, constructing the payload and handling the response.

  async def add_tracks_to_playlist_helper(
      playlist_id: str,
      track_uris: list[str],
      position: int | None = None,
  ) -> dict[str, Any]:
      """Add tracks to an existing Spotify playlist.
  
      Args:
          playlist_id: Spotify playlist ID
          track_uris: List of Spotify track URIs to add
          position: Optional position to insert tracks (0-indexed)
  
      Returns:
          Response data from Spotify API (includes snapshot_id)
  
      Raises:
          httpx.HTTPStatusError: If the API request fails
      """
      payload: dict = {"uris": track_uris}
      if position is not None:
          payload["position"] = position
  
      data = await make_spotify_request(
          f"playlists/{playlist_id}/tracks", method="POST", json=payload
      )
  
      return data