hermes-agent/website/docs/user-guide/features/spotify.md

Spotify

Hermes can control Spotify directly — playback, queue, search, playlists, saved tracks/albums, and listening history — using Spotify's official Web API with PKCE OAuth.

Unlike most Hermes integrations, Spotify requires every user to register their own lightweight developer app. Spotify does not let third parties ship a public OAuth app that anyone can use. The whole thing takes about two minutes.

Prerequisites

• A Spotify account (Free works for most tools; playback control requires Premium)
• Hermes Agent installed and running

Setup

1. Enable the toolset

hermes tools

Scroll to 🎵 Spotify, press space to toggle it on, then s to save.

2. Run the login wizard

hermes auth spotify

If you don't have a Spotify app yet, Hermes walks you through creating one:

1. Opens the Spotify developer dashboard in your browser
2. Tells you exactly what values to paste into the Spotify form
3. Prompts you for the Client ID you get back
4. Saves it to ~/.hermes/.env and continues straight into the OAuth flow

After the Spotify consent page, tokens are saved under providers.spotify in ~/.hermes/auth.json and the integration is live.

Creating the Spotify app (what the wizard asks for)

When you land on the dashboard, click Create app and fill in:

Field	Value
App name	anything (e.g. hermes-agent)
App description	anything (e.g. personal Hermes integration)
Website	leave blank
Redirect URI	http://127.0.0.1:43827/spotify/callback
Which API/SDKs?	Web API

Agree to the terms, click Save. On the next screen click Settings → copy the Client ID. That's the only value Hermes needs (no client secret — PKCE doesn't use one).

Verify

hermes auth status spotify

Shows whether tokens are present and when the access token expires. Hermes automatically refreshes on 401.

Using it

Once logged in, the agent has access to 9 Spotify tools:

Tool	Actions
spotify_playback	play, pause, skip, seek, volume, now playing, playback state
spotify_devices	list devices, transfer playback
spotify_queue	inspect queue, add tracks to queue
spotify_search	search tracks, albums, artists, playlists
spotify_playlists	list, get, create, update, add/remove tracks
spotify_albums	get album, list album tracks
spotify_saved_tracks	list, save, remove
spotify_saved_albums	list, save, remove
spotify_activity	recently played, now playing

The agent picks the right tool automatically. Ask it to "play some Miles Davis," "what am I listening to," "add the current track to my starred playlist," etc.

Sign out

hermes auth logout spotify

Removes tokens from ~/.hermes/auth.json. To also clear the app config, delete HERMES_SPOTIFY_CLIENT_ID (and optionally HERMES_SPOTIFY_REDIRECT_URI) from ~/.hermes/.env.

Troubleshooting

403 Forbidden on playback endpoints — Spotify requires Premium for play, pause, skip, and volume control. Search, playlists, and library reads work on Free.

204 No Content on now_playing — nothing is currently playing; expected behavior, not an error.

INVALID_CLIENT: Invalid redirect URI — the redirect URI registered in your Spotify app doesn't match what Hermes is using. Default is http://127.0.0.1:43827/spotify/callback. If you picked something else, set HERMES_SPOTIFY_REDIRECT_URI in ~/.hermes/.env to match.

429 Too Many Requests — Spotify rate limit. Hermes surfaces this as a friendly error; wait a minute and retry.

Advanced: custom scopes

By default Hermes requests the scopes needed for every shipped tool. To override:

hermes auth spotify --scope "user-read-playback-state user-modify-playback-state playlist-read-private"

See Spotify's scope reference for available values.

Advanced: custom client ID / redirect URI

hermes auth spotify --client-id <id> --redirect-uri http://localhost:3000/callback

Or set them permanently in ~/.hermes/.env:

HERMES_SPOTIFY_CLIENT_ID=<your_id>
HERMES_SPOTIFY_REDIRECT_URI=http://localhost:3000/callback

The redirect URI must be allow-listed in your Spotify app's settings.