Part of the Hermes Official Plugins, Nous Research's official plugins for Hermes Agent. Formerly
NousResearch/hermes-spotify, which is archived; this directory carries its full history.
Official Hermes Agent plugin for
Spotify. It gives the agent seven tools over the Spotify Web API and adds
a hermes spotify command for logging in:
| Tool | What it does |
|---|---|
spotify_playback |
Play, pause, skip, seek, shuffle, repeat, volume, current state, recently played |
spotify_devices |
List Spotify Connect devices, transfer playback |
spotify_queue |
Read the queue, add to it |
spotify_search |
Search tracks, albums, artists, playlists, shows, episodes |
spotify_playlists |
List, read, create, edit playlists; add and remove items |
spotify_albums |
Album metadata and track lists |
spotify_library |
Saved tracks and albums: list, save, remove |
This used to be built into Hermes core. It now ships as a standalone plugin with the same toolset
(spotify), tool names and schemas, env vars and stored login. If you already used Spotify with
Hermes, you don't need to do anything: hermes update (or the first start after updating) installs
and enables this plugin for you and your login keeps working. The one change is the login command:
hermes auth spotify is now hermes spotify login.
From the Hermes plugin catalog:
hermes plugins install spotify
hermes tools enable spotify # the toolset is opt-in
hermes spotify loginPlugins are installed per profile: use hermes -p <profile> plugins install spotify for another
profile. The only Python dependencies are httpx and cryptography, both of which Hermes already
ships.
Spotify requires every user to register their own lightweight developer app (Spotify does not allow
a shared public client). hermes spotify login walks you through it the first time:
- It opens https://developer.spotify.com/dashboard. Click Create app and use
http://127.0.0.1:43827/spotify/callbackas the Redirect URI, with Web API checked. HTTP is permitted on a loopback IP literal (Spotify's redirect URI rules only require HTTPS for everything else). If your dashboard refuses thehttp://form, registerhttps://127.0.0.1:43827/spotify/callbackinstead and set that URI withHERMES_SPOTIFY_REDIRECT_URI: the listener then serves https with a self-signed certificate, so the browser shows the usual "not private" warning once — accept it and continue, the connection never leaves your machine. Paste the URI into the dashboard without a trailing space: the field rejects that with "This redirect URI is not secure", which reads like a policy problem rather than a stray character. - Paste the app's Client ID at the prompt. It is saved as
HERMES_SPOTIFY_CLIENT_IDin the profile's.env, so later logins skip this step. - Approve access in the browser. Tokens are stored under
providers.spotifyin the profile'sauth.jsonand refreshed automatically.
hermes spotify login [--client-id ID] [--redirect-uri URI] [--scope "..."] [--no-browser] [--timeout S]
hermes spotify status
hermes spotify logoutOver SSH, forward the callback port first (ssh -N -L 43827:127.0.0.1:43827 user@host) and run
hermes spotify login --no-browser. See
OAuth over SSH.
| Variable | Purpose |
|---|---|
HERMES_SPOTIFY_CLIENT_ID |
Your Spotify app's Client ID (the login wizard sets it) |
HERMES_SPOTIFY_REDIRECT_URI |
Redirect URI, if you registered something other than the default |
The requested scopes are fixed at login time. The default set includes
ugc-image-upload, which the playlist cover upload needs. A profile that was
logged in before that scope was added keeps its old token, so Spotify answers
the upload with "insufficient client scope". Run hermes spotify login again
to pick up the new scope.
spotify_playlists with action: "upload_cover" replaces a playlist's cover
image. It takes an image_url - an http(s) URL or a data: URL - and
playlist_id:
{"action": "upload_cover", "playlist_id": "3lK9HyA9p04GNo4UcjuKvP",
"image_url": "https://example.com/cover.png"}The image is fetched through Hermes' image-source resolver, so the usual size
and URL-policy checks apply, and it is re-encoded as JPEG: Spotify's cover
endpoint accepts only JPEG, in a base64 body of at most 256 KB. An image that
does not fit is shrunk until it does. Local file paths are not accepted; host
an image and pass its URL, or send the bytes as a data: URL.
/spotify answers one terse line instead of spending a full agent turn, in the CLI and in every
messaging gateway (Discord, Telegram, Slack, ...):
| Command | Does |
|---|---|
/spotify play [query] |
no query resumes; with one, plays the top track match |
/spotify pause |
pauses |
/spotify skip |
skips and names the next track |
/spotify np |
now playing: track, progress, device |
/spotify queue <track> |
queues the top track match |
Anything else prints the usage line. The subcommands call the same tools the model does, so
playback state, device selection and Premium restrictions behave identically; without a stored
login they answer "Spotify not configured — run hermes spotify login". One /spotify command
keeps clear of Hermes' own /pause and /queue.
Search, playlists, albums, library, queue reads, device lists and playback state work on a Free account. Playback control (play, pause, skip, seek, volume, shuffle/repeat, queue add, transfer) needs Premium and an active Spotify Connect device: open Spotify on any phone, desktop or speaker.
Full guide: https://hermes-agent.nousresearch.com/docs/user-guide/features/spotify
Playback with no device_id goes to whichever device Spotify considers active, which is often a
phone that is not playing anything. Name the device you mean instead, in ~/.hermes/config.yaml:
spotify:
default_device_name: "Kitchen Sonos"A playback or queue action that names no device now targets that device. An explicit device_id
in the tool call still wins, and a default device that is offline is reported by name along with
the devices that are available, rather than silently falling back to Spotify's choice.
The tests import Hermes core, so run them with a hermes-agent checkout on PYTHONPATH:
PYTHONPATH=/path/to/hermes-agent python -m pytestMIT. Originally contributed to Hermes Agent core by @dlkakbs (NousResearch/hermes-agent#15096); maintained by Nous Research.
