spotify_add_tracks_to_playlist
Add tracks to existing Spotify playlists by specifying playlist ID and track URIs. Insert songs at specific positions or append to end, managing 1-100 tracks per operation for user-owned or collaborative playlists.
Instructions
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).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
Input Schema (JSON Schema)
{
"properties": {
"params": {
"$ref": "#/$defs/AddTracksToPlaylistInput"
}
},
"required": [
"params"
],
"type": "object"
}
Implementation Reference
- server.py:234-274 (handler)The main asynchronous handler function implementing the tool's core logic: calls the Spotify API helper, handles the response, and returns formatted JSON or error.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-139 (schema)Pydantic BaseModel defining the input schema with validation for playlist_id, track_uris (1-100), and optional position.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)MCP decorator registering the tool with name and annotations describing its behavior.@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-278 (helper)Utility function that makes the direct HTTP POST request to Spotify's /playlists/{id}/tracks endpoint to add the tracks.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