Smithery is now a part of Arcade.dev! Read more in our announcement here
Create and manage Spotify playlists, search music, and control playback using the Spotify Web API...
Version: 0.9.1 | Release Date: October 22, 2025
This skill directly interacts with the Spotify Web API to manage music and playlists.
šØ This skill can GENERATE IMAGES - something Claude cannot do natively! It creates custom SVG-based cover art for Spotify playlists with large, readable typography optimized for thumbnail viewing. Each cover art is dynamically generated with theme-appropriate colors, gradients, and text layouts.
Use this skill when you need to:
When to use this skill: The user wants you to create a playlist, search for music, manage their Spotify account, or generate custom cover art images.
All Spotify API operations use the SpotifyClient class from scripts/spotify_client.py. The client handles OAuth authentication and provides methods for all operations.
1. Enable Network Access (REQUIRED)
ā ļø This skill requires network access to reach api.spotify.com
In Claude Desktop, you must enable network egress:
api.spotify.com (more secure/restricted)Without network access enabled, API calls will fail with connection errors.
2. Install Dependencies
pip install -r requirements.txt
Required packages:
requests>=2.31.0 - HTTP requests for Spotify Web APIpython-dotenv>=1.0.0 - Environment variable managementcairosvg>=2.7.0 - SVG to PNG conversion for image generationpillow>=10.0.0 - Image processing for cover art creationš” Note: The
cairosvgandpillowpackages enable image generation - allowing this skill to create cover art images even though Claude cannot generate images natively!
The easiest way to initialize the client is using credentials from environment variables (loaded from .env file):
from spotify_client import create_client_from_env
# Initialize client from environment variables (.env file)
client = create_client_from_env()
# If you have a refresh token, refresh the access token
if client.refresh_token:
client.refresh_access_token()
Alternatively, you can manually provide credentials:
from spotify_client import SpotifyClient
# Initialize with credentials directly
client = SpotifyClient(
client_id="YOUR_CLIENT_ID",
client_secret="YOUR_CLIENT_SECRET",
redirect_uri="http://localhost:8888/callback",
refresh_token="YOUR_REFRESH_TOKEN" # if available
)
# Refresh to get current access token
if client.refresh_token:
client.refresh_access_token()
List ALL user playlists (with pagination):
# Get all playlists - handles pagination automatically
all_playlists = []
offset = 0
limit = 50 # Max allowed per request
while True:
playlists = client.get_user_playlists(limit=limit, offset=offset)
if not playlists:
break # No more playlists
all_playlists.extend(playlists)
offset += limit
if len(playlists) < limit:
break # Last page (fewer than limit returned)
print(f"Total playlists: {len(all_playlists)}")
for playlist in all_playlists:
print(f"- {playlist['name']} ({playlist['tracks']['total']} tracks)")
Create a new playlist:
playlist = client.create_playlist(
name="My Awesome Playlist",
description="A curated collection",
public=True
)
Search for tracks:
results = client.search_tracks(query="artist:The Beatles", limit=20)
Add tracks to playlist:
client.add_tracks_to_playlist(
playlist_id="playlist_123",
track_ids=["track_1", "track_2", "track_3"]
)
Important: Users may have more than 50 playlists. Always use pagination to get ALL playlists:
# Get ALL playlists using pagination
all_playlists = []
offset = 0
limit = 50 # Spotify's max per request
while True:
batch = client.get_user_playlists(limit=limit, offset=offset)
if not batch:
break # No more playlists to fetch
all_playlists.extend(batch)
print(f"Fetched {len(batch)} playlists (total so far: {len(all_playlists)})")
offset += limit
if len(batch) < limit:
break # Last page - fewer results than limit means we're done
print(f"\nā Total playlists found: {len(all_playlists)}")
# Display all playlists with details
for i, playlist in enumerate(all_playlists, 1):
print(f"{i}. {playlist['name']}")
print(f" Tracks: {playlist['tracks']['total']}")
print(f" Public: {playlist['public']}")
print(f" ID: {playlist['id']}")
Create a playlist containing all or most popular tracks by a specific artist:
# STEP 1: Search for the artist by name
artists = client.search_artists(query="The Beatles", limit=1)
if not artists:
print("Artist not found")
# Handle error: artist doesn't exist or name is misspelled
else:
artist_id = artists[0]['id'] # Get Spotify ID of first result
# STEP 2: Get the artist's most popular tracks
# Note: Spotify API returns up to 10 top tracks per artist
tracks = client.get_artist_top_tracks(artist_id=artist_id)
track_ids = [t['id'] for t in tracks] # Extract just the track IDs
# STEP 3: Create a new playlist and add the tracks
playlist = client.create_playlist(name="The Beatles Collection")
client.add_tracks_to_playlist(playlist['id'], track_ids)
print(f"Created playlist with {len(track_ids)} tracks")
Create thematic playlists by searching for tracks matching mood keywords:
# STEP 1: Define search queries for your theme
# Spotify search syntax: "genre:indie mood:chill" or "genre:indie year:2020-2024"
theme_queries = [
"genre:indie mood:chill", # Search for chill indie tracks
"genre:indie year:2020-2024" # Search for recent indie tracks
]
# STEP 2: Search for tracks matching each query
all_tracks = []
for query in theme_queries:
results = client.search_tracks(query=query, limit=50) # Get up to 50 per query
all_tracks.extend(results) # Combine results from all queries
# STEP 3: Remove duplicates (same track may match multiple queries)
# Use set() with track IDs to keep only unique tracks
unique_track_ids = list(set(t['id'] for t in all_tracks))
# STEP 4: Create playlist with unique tracks (limit to 100 for reasonable size)
playlist = client.create_playlist(name="Chill Indie Evening")
client.add_tracks_to_playlist(playlist['id'], unique_track_ids[:100])
print(f"Created playlist with {len(unique_track_ids[:100])} tracks")
Search for tracks with specific lyrical themes using Spotify's search:
# STEP 1: Define keywords related to lyrical content
# Note: Spotify search indexes track/artist names and some metadata,
# not full lyrics, so results are based on title/description matching
queries = ["love", "heartbreak", "summer", "midnight"]
# STEP 2: Search for tracks matching each keyword
all_tracks = []
for keyword in queries:
results = client.search_tracks(query=keyword, limit=20) # 20 tracks per keyword
all_tracks.extend(results)
# STEP 3: Remove duplicates (same track may match multiple keywords)
# Use set() with track IDs to keep only unique tracks
unique_track_ids = list(set(t['id'] for t in all_tracks))
print(f"Found {len(all_tracks)} total matches, {len(unique_track_ids)} unique tracks")
# STEP 4: Create playlist (limit to 100 tracks for reasonable size)
playlist = client.create_playlist(name="Love & Heartbreak")
client.add_tracks_to_playlist(playlist['id'], unique_track_ids[:100])
print(f"Created playlist with {len(unique_track_ids[:100])} unique tracks")
Create a playlist from a user-provided list of track URIs or search terms:
# STEP 1: Get the list of songs from the user
# User provides song names (can also use Spotify URIs like "spotify:track:...")
song_list = ["Shape of You", "Blinding Lights", "As It Was"]
# STEP 2: Search for each song and collect track IDs
track_ids = []
for song_name in song_list:
results = client.search_tracks(query=song_name, limit=1) # Get best match
if results:
track_ids.append(results[0]['id']) # Add first result's ID
print(f"ā Found: {results[0]['name']} by {results[0]['artists'][0]['name']}")
else:
print(f"ā Not found: {song_name}") # Song doesn't exist or name is wrong
# STEP 3: Create playlist with found tracks
playlist = client.create_playlist(name="My Favorites")
if track_ids:
client.add_tracks_to_playlist(playlist['id'], track_ids)
print(f"Created playlist with {len(track_ids)}/{len(song_list)} tracks")
else:
print("No tracks found - playlist is empty")
ā” UNIQUE CAPABILITY: This skill can generate images!
Claude cannot generate images natively, but this skill bypasses that limitation by creating custom SVG graphics and converting them to PNG images for Spotify playlist covers.
šØ MANDATORY: USE THE COVER ART LLM GUIDE
ā ļø DO NOT attempt to generate cover art without first reading the complete execution guide.
ā”ļø READ THIS FILE FIRST: references/COVER_ART_LLM_GUIDE.md
This guide is REQUIRED and contains:
- Complete step-by-step execution instructions
- How to analyze playlist content to determine appropriate colors
- Genre-to-color and mood-to-color mapping tables
- Typography rules and accessibility requirements
- Edge case handling and quality checklist
Do not proceed with cover art generation without consulting this guide first.
To upload cover art to Spotify, you MUST have the ugc-image-upload scope enabled:
ugc-image-upload scope is included in your authorizationpython get_refresh_token.py.env file with the new refresh tokenWithout this scope: You'll get a 401 error when trying to upload. However, you can still generate cover art images locally and upload them manually via Spotify's web/mobile app.
š Having trouble? See COVER_ART_TROUBLESHOOTING.md for detailed solutions.
ā ļø Remember: Read references/COVER_ART_LLM_GUIDE.md before generating cover art!
from cover_art_generator import CoverArtGenerator
# Initialize generator (uses same credentials as SpotifyClient)
art_gen = CoverArtGenerator(client_id, client_secret, access_token)
# Generate and upload cover art
# (Follow the LLM guide for how to determine appropriate colors)
art_gen.create_and_upload_cover(
playlist_id=playlist['id'],
title="Beast Mode", # Main title (large text)
subtitle="Gym", # Optional subtitle
gradient_start="#E63946", # Colors determined from guide
gradient_end="#1D1D1D",
text_color="#FFFFFF"
)
All cover art generation workflows, color selection guidance, and advanced features are documented in references/COVER_ART_LLM_GUIDE.md.
# Get AI-powered music recommendations based on seed artists/tracks/genres
recommendations = client.get_recommendations(
seed_artists=["artist_id_1"], # Spotify IDs of artists
seed_tracks=["track_id_1"], # Spotify IDs of tracks
limit=50 # Number of recommendations to get
)
# Returns: List of recommended tracks similar to the seeds
# Get information about the current authenticated user
profile = client.get_current_user()
# Returns: user_id, display_name, email, followers, images, country, etc.
print(f"Logged in as: {profile['display_name']}")
print(f"User ID: {profile['id']}")
# Get user's most played artists over different time periods
top_artists = client.get_top_items(
item_type="artists",
limit=20,
time_range="medium_term" # Options: short_term (~4 weeks), medium_term (~6 months), long_term (~years)
)
print(f"Top artist: {top_artists[0]['name']}")
# Get user's most played tracks
top_tracks = client.get_top_items(
item_type="tracks",
limit=20,
time_range="short_term" # Recent listening (last ~4 weeks)
)
print(f"Most played track: {top_tracks[0]['name']} by {top_tracks[0]['artists'][0]['name']}")
# STEP 1: Start playback of a playlist or album
client.start_playback(
device_id="device_123", # Optional: specific device
context_uri="spotify:playlist:playlist_id", # What to play (playlist/album/artist URI)
offset=0 # Optional: start at track 0
)
# STEP 2: Pause playback
client.pause_playback(device_id="device_123")
# STEP 3: Skip to next track
client.next_track(device_id="device_123")
# STEP 4: Check what's currently playing
current = client.get_currently_playing()
if current and current.get('item'):
track = current['item']
print(f"Now playing: {track['name']} by {track['artists'][0]['name']}")
else:
print("Nothing is currently playing")
See references/authentication_guide.md for detailed OAuth flow setup and credential management. Ensure credentials are available in environment variables or passed at initialization:
SPOTIFY_CLIENT_IDSPOTIFY_CLIENT_SECRETSPOTIFY_REDIRECT_URISPOTIFY_ACCESS_TOKEN (optional, can use refresh token)SPOTIFY_REFRESH_TOKEN (for token refresh)See references/api_reference.md for complete Spotify API endpoint documentation, rate limits, response formats, and error handling patterns.
Comprehensive Python wrapper for all Spotify Web API operations. Handles authentication, token management, rate limiting, and provides methods for:
High-level utility for intelligent playlist creation from various sources (artist, theme, lyrics, song list). Encapsulates common workflows and handles track deduplication and limit management.
Note: The features below are for developers building web applications, NOT for direct playlist creation tasks.
If the user is asking you to build an application or export data, see:
ADVANCED_USAGE.md - Application development patternsscripts/export_data.py - Export Spotify data as JSONSpotifyAPIWrapper class - Error handling for production appsFor playlist creation and music management, use the workflows above.
