Access Spotify listening history, top artists/tracks, and get personalized recommendations via the Spotify Web API. Use when fetching a user's recent plays, analyzing music taste, or generating recommendations. Requires one-time OAuth setup.
Access Spotify listening history and get personalized recommendations.
Run the setup wizard:
bash skills/spotify-history/scripts/setup.sh
This guides you through:
Create Spotify Developer App
Clawd (or any name)Personal assistant integrationhttp://127.0.0.1:8888/callback ⚠️ Use exact URL!Store Credentials
Option A: Credentials file (recommended)
mkdir -p credentials
cat > credentials/spotify.json <<EOF
{
"client_id": "your_client_id",
"client_secret": "your_client_secret"
}
EOF
chmod 600 credentials/spotify.json
Option B: Environment variables
# Add to ~/.zshrc or ~/.bashrc
export SPOTIFY_CLIENT_ID="your_client_id"
export SPOTIFY_CLIENT_SECRET="your_client_secret"
Authenticate
With browser (local machine):
python3 scripts/spotify-auth.py
Headless (no browser):
python3 scripts/spotify-auth.py --headless
Follow the prompts to authorize via URL and paste the callback.
Tokens are saved to ~/.config/spotify-clawd/token.json and auto-refresh when expired.
# Recent listening history
python3 scripts/spotify-api.py recent
# Top artists (time_range: short_term, medium_term, long_term)
python3 scripts/spotify-api.py top-artists medium_term
# Top tracks
python3 scripts/spotify-api.py top-tracks medium_term
# Get recommendations based on your top artists
python3 scripts/spotify-api.py recommend
# Raw API call (any endpoint)
python3 scripts/spotify-api.py json /me
python3 scripts/spotify-api.py json /me/player/recently-played
short_term — approximately last 4 weeksmedium_term — approximately last 6 months (default)long_term — all timeTop Artists (medium_term):
1. Hans Zimmer [soundtrack, score]
2. John Williams [soundtrack, score]
3. Michael Giacchino [soundtrack, score]
4. Max Richter [ambient, modern classical]
5. Ludovico Einaudi [italian contemporary classical]
When user asks about music:
spotify-api.py recentspotify-api.py top-artistsspotify-api.py recommend + add your own knowledgeFor recommendations, combine API data with music knowledge to suggest similar artists not in their library.
credentials/spotify.json exists or environment variables are setbash skills/spotify-history/scripts/setup.sh to create credentialspython3 scripts/spotify-auth.py (or with --headless if no browser)bash skills/spotify-history/scripts/setup.shcredentials/spotify.json with correct Client ID/Secretrm ~/.config/spotify-clawd/token.json
python3 scripts/spotify-auth.py
--headless flag: python3 scripts/spotify-auth.py --headlesshttp://127.0.0.1:8888/callback?code=...)127.0.0.1 (local only) for securityuser-read-recently-played — recent listening historyuser-top-read — top artists and tracksuser-read-playback-state — current playbackuser-read-currently-playing — currently playing track