Spotify Discovery MCP

A Spotify discovery playlist run by a scheduled agent, where the model only has to judge the music.

Why · How a lane run works · Pick rules · Setup · Tools · Spotify API notes

An MCP server that runs a Spotify discovery playlist for a scheduled agent. Fetching, verifying, deduplicating and saving state are all code, so the agent's model only has to judge music.

Status: in daily use. The design comes from two weeks of a Hermes cron setup that built a playlist each Tuesday and Friday: six jobs, one per genre "lane", on a local Qwen 27B model, each adding tracks to that day's playlist. It ran on Hermes from 2026-10-03. Since 2026-10-18 it runs from spotify-discovery, a plain scheduled job that drives this server over MCP, does the research in a bounded tool loop and posts the reports to Discord. The six lanes there take about 20 minutes in all instead of most of a morning, and the feed's request budget (below) keeps them inside Spotify's daily quota, so it can build a playlist every day. The Hermes setup below still works.

Why

Those six jobs work, but a model does all their bookkeeping. In twelve runs (2026-09-29 to 10-02):

• Every full rewrite of the shared playlist file was refused (18 of 18), so the model fell back to hand-written patches. One patch inserted a duplicate block, which the model then had to repair.

• One job added the same six tracks twice, which left 5 duplicates in the playlist. Two earlier days each got more than one playlist.

• The history file holds duplicates the model's dedup missed. The model reads the whole file, about 16k characters and growing, every run.

• About 536k characters of raw Spotify search JSON went into the model's context, one search per turn.

• A web-research subagent used all 50 of its searches and returned nothing 5 times. That's about 10 minutes lost each time.

• One track reported "not on Spotify" was there. A plain search missed it, but a track:"…" artist:"…" search finds it.

A run took 20 to 57 messages, and most of those messages were bookkeeping. This server takes the bookkeeping over, using job-ledger, which comes from the same work on medium-reader-mcp and substack-reader-mcp.

Related MCP server: mcp-spotify

How a lane run works

Each step is done either by code (this server) or by the model.

The research never passes through the main model. On 2026-10-03 the first live run had Qwen copy the subagent's reply into verify_tracks; it mangled the JSON escaping four times, and the run ran out of road before finishing. Now the subagent calls verify_tracks itself and returns only "DONE".

That's 5 turns for the main model, down from 20–57. The model never sees the history, the playlist file or other lanes, and has no file tools. docs/design.md has the details, and docs/discovery-tools.md follows one run with a diagram, each tool's arguments and real output.

Where picks come from, and how they're mixed

There are two sources of candidates, and the mix between them is the main thing to tune.

The feed (K and C refs) is new releases from labels and artists this lane already knows. It's fetched from Spotify by code, so every item exists, has a release date, and hasn't been recommended before. The feed is reliable, but it can only find what you already know about.

Web finds (W refs) come from the research subagent: blogs, Bandcamp, label pages, Reddit. They're how the lane discovers new names. They're checked on Spotify before the model can pick them.

Web research always runs, even when the feed has plenty. It's the only way the lane finds anything new, so the model doesn't get to skip it.

The rules

Each lane has a target (for example 3–6 tracks) and limits, set in lanes.json:

The model decides quality; the server enforces quantities. The model lists its picks best first. discovery_finish keeps them in that order and drops any that would break a limit, starting from the end of the list. The report says what was dropped and why. It never refuses the whole call, because a model stuck resending a list one item too long would stall the job.

Examples

Take a lane with target: [3, 6], max_feed_picks: 3, max_core_picks: 2. The feed offers 10 tracks.

A. The web research finds nothing usable (nothing verified on Spotify). The feed limit lifts, because there's nothing to save room for. The model picks the best 3–6 of the 10. Unpicked feed tracks carry over to the next run.

B. The web research finds 10, and 7 are verified on Spotify. The model picks up to 6, with at most 3 from the feed. Any of these is fine:

• 6 web picks, no feed picks

• 3 web picks and 3 feed picks

• 2 web picks, 1 feed pick, and stop at 3, because nothing else fits well

If the model sends 4 feed picks, finish keeps its top 3 feed picks and reports the 4th as dropped. Unpicked tracks from both sources carry over.

C. The feed is empty, and the web research finds 2. The model picks what fits, perhaps both. The report says the lane came back thin.

D. Half the picks are by artists you already like. With max_core_picks: 2, only the first 2 of those (in the model's order) are kept. It's good to surface a new release by an artist you like, but a discovery playlist shouldn't be mostly them.

Nothing good is lost

The feed is fetched by date ("released since this source was last checked"), but the candidates themselves are kept in a pool, which isn't date-based. Unpicked candidates come back on later runs, marked with how often they've been passed over, until one of these happens:

• they're picked,

• the model rejects them outright (at most 3 per run, so a model that rejects everything it didn't pick can't empty the pool),

• they've been in the pool carry_days days (default 21, counted from when they were first shown, so it means the same however often the lanes run; before 0.5.0 it was carry_runs, a number of runs),

• they're older than max_age_days.

Web finds that verified but weren't picked go into the same pool. Web finds that aren't on Spotify yet (an album due out in three weeks, a release out that morning) are kept as pending. Each run checks them quietly, and they join the pool once they appear.

Staying inside Spotify's quota

Development Mode apps get daily request quotas that Spotify doesn't publish. Since July 2026 they're counted per developer account, not per app, and endpoints are grouped into quota buckets that each have their own limit (Spotify: quota modes). Past a bucket's limit, its requests fail with 429 QUOTA_EXCEEDED until 24 hours after the window's first request. The others keep working. On 2026-10-19 /artists/{id}/albums was blocked after about 76 calls in a day, while /search (about 400 that day) and /albums/{id} still answered. Before 0.6.0 the feed used that endpoint for every lane artist, so the fifth and sixth lanes ran out on 10-16, 10-18 and 10-19.

Since 0.6.0:

• Artists are found by search (artist:"…" tag:new, keeping only releases that name the artist), like labels, so /artists/{id}/albums isn't used at all.

• A block ends only what used that endpoint. The client remembers blocks per endpoint, and a block during the feed or the pending check ends that step with what it found; the run goes on.

• Web first, known sources only if short (discovery_begin {feed: false} then discovery_fill; see discovery-tools.md). The known sources are checked for only as many tracks as the run is short, and pending web finds last, at most once a week each.

• An album is read once per process, so a compilation's tracks cost one album request, not one each.

Within its budget, the feed checks the lane's known labels and artists longest-waiting first, and stops once it has feed_tracks new tracks (enough for the model to choose from) or has used feed_requests requests (the ceiling on a quiet day, when most sources have nothing new). The sources it didn't reach go first next run. Each source looks back to its own last check, at most 30 days, so a source left out of a run loses nothing; its releases arrive a run later. No source is starved by its place in the list. Before 0.5.0 the feed took the first 20 labels and 20 artists in a fixed order, so the ones after that were never checked.

Set them in lanes.json, under defaults or per lane. A run that doesn't finish marks nothing as checked. Each release costs one request, since the album response carries its tracks. The work list says when sources were left over, and each run file records Spotify requests by step (requests_by_step: pending checks, feed, verify, finish), so you can see where a lane's quota goes.

The lane learns new labels

When research turns up a new label, discovery_finish saves it to that lane as found, and the next run's feed includes it. Spotify has no label IDs, and searching by label name also finds labels with similar names, so the first time a release on the label turns up, the server saves the label's exact name from the release's ℗ line. After that, the feed only takes releases whose ℗ line names that label. A found label is promoted once one of its tracks is picked. It's dropped after a run of quiet runs, and the report says so. Labels you list in lanes.json are never dropped automatically. The report only notes when one has gone quiet.

Setup

1. Install

npm install -g spotify-discovery-mcp   # one bundled file, no dependencies

From source instead: clone the repo, then npm install && npm test && npm run build (it bundles everything into dist/cli.js), and use node dist/cli.js in place of spotify-discovery-mcp.

2. Log in to Spotify

The server has its own login and refresh token, so it can't invalidate another client's (Hermes's own Spotify tools, if you use them). Spotify gives new Development Mode apps one client id per developer, so use the app you already have, and register its redirect URI if it isn't there yet.

SPOTIFY_DISCOVERY_AUTH=./auth.json spotify-discovery-mcp login --client-id <your app's client id>
# headless, or when the browser can't reach 127.0.0.1:
SPOTIFY_DISCOVERY_AUTH=./auth.json spotify-discovery-mcp login --client-id <id> --paste

The default redirect URI is http://127.0.0.1:43827/spotify/callback; change it with --redirect-uri. The token file is written with mode 0600. Copy it to the host, to SPOTIFY_DISCOVERY_AUTH or $SPOTIFY_DISCOVERY_DIR/auth.json.

3. The data directory

SPOTIFY_DISCOVERY_DIR holds:

• lanes.json: yours. Start from hermes/lanes.example.json, which has the six lanes from the original cron prompts. playlist.name names each day's playlist: {YYMMDD} (the default since 0.5.0, such as 261018), {YYYYMMDD} or {YYYY-MM-DD}, with any text around it. Keep it short: Spotify's apps don't scroll long titles, so a name like hermes20261018 gets cut off, and a name that starts with the date sorts by date.

• taste_profile.json: optional; core_artists from your listening, for max_core_picks.

• The state the server writes: history.json, days.json, lanes/<lane>.json, runs/.

To carry over what the old jobs recommended, run spotify-discovery-mcp import <old dir> once. It reads recommendation_history.json and today_playlist.json.

spotify-discovery-mcp status checks the login and shows each lane.

4. Running the lanes

spotify-discovery is a standalone scheduled job that runs the lanes against this server; its README covers setup. That's how I run it.

To run the lanes on Hermes Agent instead, add the server to config.yaml:

mcp_servers:
  spotify-discovery:
    command: node
    args: [/opt/data/mcp/spotify-discovery-mcp/dist/cli.js]
    env:
      SPOTIFY_DISCOVERY_DIR: /opt/data/sandbox/spotify_discovery
      SPOTIFY_DISCOVERY_AUTH: /opt/data/mcp/spotify-discovery-home/auth.json

Install hermes/SKILL.md as the spotify-discovery skill. Then for each lane job:

• set enabled_toolsets to ["delegation", "web", "spotify-discovery"];

• set skills to ["spotify-discovery", "searxng-search"];

• set the prompt to "Run the spotify-discovery skill for lane a-dnb." (with that job's lane);

• set deliver to local.

The reports reach Discord through a no-model job instead, because copying a long report is where a weak model fails. In the second live run, Qwen got a perfect report back from discovery_finish, thought for 13 minutes, then sent its persona prompt instead. Copy hermes/spotify_discovery_report.sh to Hermes's scripts/ and create a no_agent job that runs it every 5 minutes during the lanes' window, delivering to the channel the lanes used. Empty output is a silent run.

Settings

Tools

Spotify API notes

This uses Spotify's Web API as a Development Mode app. The February 2026 changes removed several things the design would otherwise use: label fields, artist genres, related artists, recommendations and new-releases browsing. Search now returns at most 10 results per page. Development Mode also has an unpublished daily quota; see Staying inside Spotify's quota. docs/spotify-api.md lists what was tested and what still works. Genre, BPM and key come from other sources instead; see docs/metadata-sources.md.

MIT licensed.