Spotify Playlist MCP Server

Instructions

Implementation Reference

• server.py:179-222 (handler)

  The main asynchronous handler function for the spotify_create_playlist tool. It validates inputs via Pydantic, calls the create_playlist_helper utility to interact with the Spotify API, formats a JSON success response, and handles errors.
  async def spotify_create_playlist(params: CreatePlaylistInput) -> str: """Create a new empty Spotify playlist for the authenticated user. Creates an empty playlist in the user's library. Use spotify_add_tracks_to_playlist to add tracks after creation. Args: - name: Playlist name, 1-100 characters - description: Optional description, max 300 characters - public: Whether playlist is public (default: True) - collaborative: Whether others can modify (default: False, cannot be True if public is True) Returns: JSON: {"success": true, "playlist_id": "...", "name": "...", "url": "...", "message": "..."} Examples: - "Create a new workout playlist" -> name="Workout Mix" - "Make a private playlist" -> name="My Mix", public=False - "Create collaborative playlist" -> collaborative=True, public=False Errors: Returns error for collaborative+public, auth failure (401), missing scopes (403), rate limits (429). """ try: data = await create_playlist_helper( name=params.name, description=params.description, public=params.public, collaborative=params.collaborative, ) return json.dumps( { "success": True, "playlist_id": data["id"], "name": data["name"], "url": data["external_urls"]["spotify"], "message": f"Successfully created playlist '{data['name']}'", }, indent=2, ) except Exception as e: return handle_spotify_error(e)
• spotify_mcp/types.py:102-120 (schema)

  Pydantic model defining the input schema for spotify_create_playlist, including validation rules for name, description, public, and collaborative fields.
  class CreatePlaylistInput(BaseModel): """Input model for creating a playlist.""" model_config = ConfigDict(str_strip_whitespace=True, validate_assignment=True) name: str = Field( ..., description="Name of the playlist", min_length=1, max_length=100 ) description: str | None = Field( default=None, description="Description of the playlist", max_length=300 ) public: bool = Field( default=True, description="Whether the playlist should be public" ) collaborative: bool = Field( default=False, description="Whether others can modify the playlist (cannot be true if public is true)", )
• server.py:169-178 (registration)

  The @mcp.tool decorator that registers the spotify_create_playlist function as an MCP tool, specifying its name and operational hints.
  @mcp.tool( name="spotify_create_playlist", annotations={ "title": "Create Spotify Playlist", "readOnlyHint": False, "destructiveHint": False, "idempotentHint": False, "openWorldHint": True, }, )
• spotify_mcp/utils.py:207-249 (helper)

  Supporting utility function that performs the core Spotify API interaction: fetches user ID, constructs payload, and POSTs to /users/{user_id}/playlists endpoint.
  async def create_playlist_helper( name: str, description: str | None = None, public: bool = True, collaborative: bool = False, ) -> dict[str, Any]: """Create a new Spotify playlist for the authenticated user. Args: name: Name of the playlist description: Optional description of the playlist public: Whether the playlist should be public collaborative: Whether others can modify the playlist Returns: Playlist data from Spotify API Raises: ValueError: If collaborative and public are both True httpx.HTTPStatusError: If the API request fails """ if collaborative and public: raise ValueError("A playlist cannot be both collaborative and public") # Get current user ID user_data = await make_spotify_request("me") user_id = user_data["id"] # Create playlist payload = { "name": name, "public": public, "collaborative": collaborative, } if description: payload["description"] = description playlist_data = await make_spotify_request( f"users/{user_id}/playlists", method="POST", json=payload ) return playlist_data