spotify_get_user_playlists

Instructions

Retrieves all playlists owned by or followed by the authenticated user. Results are
paginated. Use to browse playlists or find playlist IDs.

Args:
    - limit: Number of playlists to return, 1-50 (default: 20)
    - offset: Starting position for pagination (default: 0)
    - response_format: 'markdown' or 'json'

Returns:
    Markdown: List with playlist name, ID, track count, public status, description, URL
    JSON: {"total": N, "count": N, "offset": N, "playlists": [{id, name, description, public, collaborative, tracks, owner, external_urls}], "has_more": bool}

Examples:
    - "Show me my playlists" -> List all user playlists
    - "Find my workout playlist" -> Browse to find specific one
    - Need playlist ID -> Get ID from the list

Errors: Returns "No playlists found." if none exist, or error for auth failure (401), missing scopes (403), rate limits (429).

Implementation Reference

• server.py:276-285 (registration)

  Registers the 'spotify_get_user_playlists' tool with the MCP server using the @mcp.tool decorator, including metadata annotations.

  @mcp.tool(
      name="spotify_get_user_playlists",
      annotations={
          "title": "Get User's Spotify Playlists",
          "readOnlyHint": True,
          "destructiveHint": False,
          "idempotentHint": True,
          "openWorldHint": True,
      },
  )

• spotify_mcp/types.py:141-154 (schema)

  Pydantic BaseModel defining the input schema for the tool, including limit (1-50), offset (>=0), and response_format (markdown/json).

  class GetUserPlaylistsInput(BaseModel):
      """Input model for getting user playlists."""
  
      model_config = ConfigDict(str_strip_whitespace=True, validate_assignment=True)
  
      limit: int | None = Field(
          default=20, description="Number of playlists to return", ge=1, le=50
      )
      offset: int | None = Field(default=0, description="Offset for pagination", ge=0)
      response_format: ResponseFormat = Field(
          default=ResponseFormat.MARKDOWN,
          description="Output format: 'markdown' or 'json'",
      )

• server.py:286-357 (handler)

  The core handler function that executes the tool: makes API request to /me/playlists, handles pagination, formats output as markdown list of playlists or JSON structure with details.

  async def spotify_get_user_playlists(params: GetUserPlaylistsInput) -> str:
      """Get a list of the current user's Spotify playlists.
  
      Retrieves all playlists owned by or followed by the authenticated user. Results are
      paginated. Use to browse playlists or find playlist IDs.
  
      Args:
          - limit: Number of playlists to return, 1-50 (default: 20)
          - offset: Starting position for pagination (default: 0)
          - response_format: 'markdown' or 'json'
  
      Returns:
          Markdown: List with playlist name, ID, track count, public status, description, URL
          JSON: {"total": N, "count": N, "offset": N, "playlists": [{id, name, description, public, collaborative, tracks, owner, external_urls}], "has_more": bool}
  
      Examples:
          - "Show me my playlists" -> List all user playlists
          - "Find my workout playlist" -> Browse to find specific one
          - Need playlist ID -> Get ID from the list
  
      Errors: Returns "No playlists found." if none exist, or error for auth failure (401), missing scopes (403), rate limits (429).
      """
      try:
          query_params = {"limit": params.limit, "offset": params.offset}
  
          data = await make_spotify_request("me/playlists", params=query_params)
  
          playlists = data.get("items", [])
          total = data.get("total", 0)
  
          if not playlists:
              return "No playlists found."
  
          # Format response
          if params.response_format == ResponseFormat.MARKDOWN:
              lines = [
                  "# Your Spotify Playlists\n",
                  f"Showing {len(playlists)} of {total} playlists\n",
              ]
  
              for playlist in playlists:
                  lines.append(f"## {playlist['name']}")
                  lines.append(f"- Playlist ID: `{playlist['id']}`")
                  lines.append(f"- Tracks: {playlist.get('tracks', {}).get('total', 0)}")
                  lines.append(f"- Public: {playlist.get('public', False)}")
                  if playlist.get("description"):
                      lines.append(f"- Description: {playlist['description']}")
                  lines.append(f"- URL: {playlist['external_urls']['spotify']}\n")
  
              has_more = total > params.offset + len(playlists)
              if has_more:
                  next_offset = params.offset + len(playlists)
                  lines.append(
                      f"\n*More playlists available. Use offset={next_offset} to see more.*"
                  )
  
              return "\n".join(lines)
          else:
              # JSON format
              return json.dumps(
                  {
                      "total": total,
                      "count": len(playlists),
                      "offset": params.offset,
                      "playlists": playlists,
                      "has_more": total > params.offset + len(playlists),
                  },
                  indent=2,
              )
  
      except Exception as e:
          return handle_spotify_error(e)