spotify_create_playlist

Instructions

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).

Implementation Reference

• server.py:179-222 (handler)

  Main handler function that executes the tool logic by calling the create_playlist_helper and formatting the JSON response.

  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 input schema defining parameters for creating a playlist: name, description, public, collaborative.

  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)

  MCP decorator registering the tool with name 'spotify_create_playlist' and metadata annotations.

  @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 helper function that makes the actual Spotify API POST request to create the user's playlist.

  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