Golden Hour Selector
Enriches exported tracks with Last.fm popularity data using a free Last.fm API key, with cached and resumable enrichment runs.
Enriches exported track metadata using MusicBrainz, adding original release year, curated genres, artist country/area/home town, artist type and active years, and optionally album community ratings; lookups are cached and resumable.
Integrates with the Spotify Web API to search tracks, control playback and Spotify Connect devices, inspect now-playing state, list playlists and their tracks, export playlists and Liked Songs to CSV, create playlists, and add tracks in order.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Golden Hour Selector search Spotify for Chet Baker and play the top track"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Golden Hour Selector
Know your music, then build better playlists. Golden Hour Selector is a free, local toolkit for Spotify with two halves:
A dashboard of your whole listening life: every song you ever played, joined to your playlists and enriched with genres, countries and popularity.
A playlist builder: an MCP server your agent uses to search, export and create playlists from your own library. It is the tool behind our curated Golden Hour Selection playlists, such as Bristol After Dark.
It is MIT licensed, free forever, needs no account of ours and runs no server
anywhere: everything stays on your computer and the dashboard only listens on
127.0.0.1. Package: @neleus/golden-hour-selector.
The MCP server also controls playback and works with your library: list your
playlists, export them to an enriched CSV, create playlists and add tracks.
It runs locally over stdio, uses OAuth Authorization
Code + PKCE (no client secret), and keeps its token on your own machine. Its
command is available as both golden-hour-selector and mcp-spotify, so
existing MCP setups keep working.
Free to use, fork and change under the MIT licence. Built and governed inside Neleus; it has no dependency on Neleus and works with any MCP client (Claude Code, Claude Desktop, and others).
Your whole listening life in one dashboard
You will see total plays and hours, plays per year, your top artists and songs all time and per year, forgotten favourites (songs you played a lot and then not for two years), the songs you skip most, and songs you play a lot that are in none of your playlists. Below that sits the library view: genres, artist countries, decades, playlist sizes, popular songs and album ratings.
This guide is written so you can hand it to an agent (Claude Code or any other MCP client) and let it do the typing. Each step says what you do yourself.
1. Ask Spotify for your extended streaming history (you, once)
Open Spotify's privacy settings at https://www.spotify.com/account/privacy/,
tick Extended streaming history and request it. Spotify emails you a link
to my_spotify_data.zip. It can take up to 30 days, so do this first and do
the other steps while you wait. The basic "Account data" export is not enough:
it covers only the last year.
2. Create a free Spotify developer app (you, 2 minutes)
Go to https://developer.spotify.com/dashboard and create an app. Any name and description will do.
Add the redirect URI
http://127.0.0.1:8888/callbackexactly.Tick "Web API" and save. Copy the Client ID. There is no secret to copy.
Spotify requires the app owner to have Premium for development apps.
3. Install and authorise (your agent can do this)
git clone https://github.com/neleus-agent/golden-hour-selector && cd golden-hour-selector
npm install && npm run build
SPOTIFY_CLIENT_ID=<your id> node dist/index.js auth # opens your browser once
SPOTIFY_CLIENT_ID=<your id> node dist/index.js auth status # should say all scopes grantedOptionally register it with your agent so it can also play music and build playlists for you, for example in Claude Code:
claude mcp add spotify --env SPOTIFY_CLIENT_ID=<your id> -- node /path/to/dist/index.js4. Export your playlists and Liked Songs (a few minutes)
SPOTIFY_CLIENT_ID=<your id> node dist/index.js exportThis writes tracks.csv and playlists.csv to
~/Downloads/spotify-export-<date>/. Only playlists you own or collaborate on
can be read; see the platform limits further down.
5. Enrich it for free (optional, resumable)
node dist/index.js enrich ~/Downloads/spotify-export-<date>/tracks.csv --popularityMusicBrainz, ListenBrainz and Deezer need no key. Add Last.fm with a free key from https://www.last.fm/api/account/create:
LASTFM_API_KEY=<your key> node dist/index.js enrich ~/Downloads/spotify-export-<date>/tracks.csv --lastfmEvery answer is cached, so you can stop at any time and run the same command
again to carry on. Honest run times for a library of about 10,000 songs, at
the polite rates these free services ask for: MusicBrainz genres and countries
take roughly 10 to 30 minutes, Deezer and ListenBrainz popularity about half an
hour, Last.fm close to an hour, and --ratings about an hour per 4,000
albums. Smaller libraries are proportionally faster; a re-run is nearly free.
6. Import your streaming history (seconds)
When the zip arrives, point the importer at it (or at the folder you unzipped it into):
node dist/index.js import-history ~/Downloads/my_spotify_data.zipIt finds your newest export folder by itself (use --library <csv> to pick a
file, --out <folder> to write elsewhere) and writes one file next to it:
tracks-history.csv. Privacy, enforced in code and tests:
From each stream it keeps only the track URI, timestamp, milliseconds played, skipped, and the track, artist and album names. Everything else in Spotify's export (network address, device, country, client and so on) is dropped in memory and never written.
Only per-song totals are written: plays (from 30 seconds, as Spotify counts them), minutes, skip rate, first and last play date, peak year and plays per year. There is no list of individual streams.
Podcasts and audiobooks are skipped.
The zip is read in memory and never unpacked to disk. You can delete it afterwards.
7. Open the dashboard
npm run dashboardIt opens http://127.0.0.1:8765/ (or the next free port) in your browser and
shows the newest tracks-history.csv. Pass a file to show another one:
npm run dashboard -- path/to/file.csv. The server answers only on this
computer and only serves the page and that one file. Press Ctrl+C to stop it.
8. Things to ask your agent
"Build me a private playlist of my forgotten favourites from tracks-history.csv."
"Which songs do I play a lot that are in none of my playlists? Put the top 50 in a new playlist called Hidden Heavy Rotation."
"What was my top artist each year? Write it as a short story of my listening life."
"Show me the songs I skip most and which of my playlists they are in."
"Make a playlist of the songs I played most in 2019."
"Which genres did I discover in the last two years?"
Related MCP server: AKIMCP
Tools
Tool | What it does |
| Search a track by name and play it (optionally on a named device) |
| Playback control |
| Current track, device and progress |
| Play a mood preset (focus, chill, ...) |
| Spotify Connect devices; move playback |
| Start the Spotify desktop app |
| Resolve a song name to |
| Your playlists, with owner, size and whether their tracks are readable |
| Tracks of one playlist (by name, id, URI or URL) |
| Write |
| New playlist, private unless you say otherwise |
| Add |
Playback and playlist writes are logged to an append-only JSONL audit (metadata only, never tokens).
Setup
Create an app at https://developer.spotify.com/dashboard. Add the redirect URI
http://127.0.0.1:8888/callbackexactly. Copy its Client ID.Build and authorise once:
npm install && npm run build SPOTIFY_CLIENT_ID=<your id> node dist/index.js auth # opens the browser SPOTIFY_CLIENT_ID=<your id> node dist/index.js auth status # lists any missing scopesRegister it with your MCP client, for example Claude Code:
claude mcp add spotify --env SPOTIFY_CLIENT_ID=<your id> -- node /path/to/dist/index.js
The token is stored at ~/.ai/mcp-spotify/spotify.json (override with
SPOTIFY_TOKEN_PATH). See .env.example for every setting. New versions that
add scopes need one fresh auth; auth status tells you.
Export to CSV
SPOTIFY_CLIENT_ID=<your id> node dist/index.js export [--out DIR] [--no-liked] [--no-enrich]The default folder is ~/Downloads/spotify-export-<date>/ (or SPOTIFY_EXPORT_DIR).
tracks.csv has one row per playlist entry: playlist, position, added date,
track, artists, album, album type, release date, year, duration, explicit,
ISRC, genres (from the artists), and tempo, key, time signature, energy,
danceability and valence when Spotify still returns audio features for your
app. playlists.csv lists every playlist and whether it was exported or why
it was skipped. Files are UTF-8 with a BOM, so Excel opens accents correctly.
Enrich with MusicBrainz
node dist/index.js enrich ~/Downloads/spotify-export-<date>/tracks.csv [--ratings] [--max-ratings N]Needs no Spotify login. It writes tracks-enriched.csv next to the input and
adds: original release year (not the remaster year), main genre plus up to five
genres from MusicBrainz's curated genre list, artist country, area and home
town, artist type and active years, and with --ratings the album's community
rating out of 5 with its vote count. Songs are matched by ISRC first, then by
exact artist name.
MusicBrainz allows one request per second, so lookups are batched (40 per
request) and every answer is cached in ~/.ai/mcp-spotify/musicbrainz-cache.json.
A run that stops resumes where it left off; a re-run is nearly free. Ratings
take one request per album, so --ratings is the slow part (about an hour per
4,000 albums). Set MUSICBRAINZ_CONTACT to a URL or address of yours to
identify your client to MusicBrainz, as they ask. MusicBrainz core data is CC0.
Song popularity (--popularity, --lastfm)
node dist/index.js enrich tracks.csv --popularity # ListenBrainz + Deezer, no key needed
LASTFM_API_KEY=... LASTFM_USER=you node dist/index.js enrich tracks.csv --lastfm # adds Last.fmAdds per song: deezer_rank (Deezer streaming popularity), lb_listeners and
lb_listens (ListenBrainz), lastfm_listeners and lastfm_plays (global
Last.fm), my_plays (your own Last.fm scrobbles, fetched fresh every run),
bpm where Deezer has it, and popularity: a 0-100 percentile within your
own library, averaged over the sources that know the song. High is a
well-known track, low a deep cut.
Last.fm needs a free API key (last.fm/api/account/create). To fill
my_plays, connect Spotify scrobbling in Last.fm under Settings > Applications; it counts plays from that day on.Each user brings their own Last.fm key. Last.fm's API terms allow non-commercial use and ask for attribution. Deezer and ListenBrainz are used through their public APIs at a polite rate; answers are cached in
~/.ai/mcp-spotify/popularity-cache.json.
Library viewer
node dist/index.js viewerOpens viewer/index.html, a single offline page: drop tracks-enriched.csv
(or tracks.csv) on it to see totals, genres, artist countries, decades, top
artists, playlist sizes, the highest-rated albums and a searchable track list,
filterable per playlist. The file is read in the browser and never uploaded.
Dropping tracks-history.csv adds the listening-life views; npm run dashboard
serves the same page on 127.0.0.1 and loads the file for you.
Spotify platform limits (February 2026 development mode)
The app owner needs an active Spotify Premium subscription; a development-mode app allows 5 users.
Tracks are only readable for playlists you own or collaborate on. Playlists you only follow (Spotify-made or other people's) show up in
playlists.csvas skipped. To export one, open it in Spotify and use "Add to other playlist" to copy it into a playlist of your own.Audio features (tempo, key) are closed to apps registered after 27 November 2024; those columns then stay empty. Artist popularity and follower counts were removed; genres may be empty for smaller artists.
Search returns at most 10 results per call.
Use inside Neleus
Neleus uses this server as one of its connectors. The free Neleus Client edition ships without it; to add it, build it and register it as an MCP server like any other client would.
Development
npm test # vitest, no network
npm run lint # tsc --noEmit
npm run build # tsup -> dist/
npm run gate # the public gate (see below)
npm run hooks # run the gate before every commit and push in your cloneSecurity and privacy for contributors
Your listening data is personal. It never belongs in this repository, and three layers make sure it stays out:
Never commit exports. No CSV, TSV or zip files, no Spotify export (
my_spotify_data*,Streaming_History*), no caches, no.env, no token files..gitignoreblocks them; test fixtures are invented and built in code.The gate.
npm run gatefails if any tracked file, or any file anywhere in the git history, has one of those names; if a tracked file contains a network address (loopback and documentation ranges are fine) or a personal streaming-history key; or if a file or any past revision contains a line from your own private markers file. That optional file lives outside the repository, at~/.ai/golden-hour-selector/private-markers.txt(or the path inGOLDEN_HOUR_SELECTOR_PRIVATE_MARKERS): put your name, usernames and device or room names in it, one per line.npm run hooksruns the gate before every commit and push.CI. Every push and pull request runs the build, the tests (including the privacy tests) and the gate over the full history.
If the gate finds something in history, deleting the file is not enough: the history has to be rewritten before anything is published.
Licence
MIT. See LICENSE.
Available Tools
15 toolsadd_to_playlistA
Add tracks to a playlist the user owns or collaborates on, by spotify:track: URIs (resolve names first with search). Appends in order unless a position is given.
Inputs: uris (required), playlist (required), position.
create_playlistB
Create a new playlist in the user's account (private by default). Returns its id and URL.
Inputs: name (required), public, description.
export_playlistsA
Export all readable playlists (plus Liked Songs) to CSV files enriched with album, year, ISRC, genres and, where Spotify still allows, tempo/key. Writes tracks.csv + playlists.csv and returns their paths and a summary. Can take minutes for large libraries.
Inputs: enrich, out_dir, include_liked.
launch_appA
Launch the local Spotify desktop app so it becomes a controllable device, then wait briefly and report available devices. Use when no active device is available before playing.
Inputs: no named parameters.
list_devicesA
List the available Spotify Connect devices (id, name, type, is_active, volume_pct). Use to discover device names — e.g. linked Sonos rooms — before playing or transferring to one.
Inputs: no named parameters.
list_playlistsA
List the user's Spotify playlists (owned and followed) with id, owner, track count and whether their tracks are readable (owned or collaborative).
Inputs: no named parameters.
now_playingA
Get the current Spotify playback state: track, artist, album, device, progress, and volume.
Inputs: no named parameters.
pause_resumeA
Pause, resume, or toggle Spotify playback on the active device. Returns the now_playing state.
Inputs: action.
playA
Search Spotify for a track by name and start playing it. Plays on the active device, or on a named device (e.g. a Sonos room) when 'device' is given. Returns the now_playing state.
Inputs: query (required), device.
playlist_tracksA
List the tracks of one playlist (by name, id, spotify: URI or open.spotify.com URL). Only playlists the user owns or collaborates on are readable.
Inputs: playlist (required), limit.
play_moodA
Play music matching a mood (e.g. focus, chill, energetic, happy). Plays on the active device, or on a named device (e.g. a Sonos room) when 'device' is given. Falls back to search on an unknown mood.
Inputs: mood (required), device.
searchA
Search Spotify for tracks by name and return the top matches with their spotify: URIs. Does NOT play — use to resolve a song name to a URI (e.g. to then play it on a Sonos room via mcp-sonos).
Inputs: query (required).
skipA
Skip to the next or previous track on the active Spotify device. Returns the now_playing state.
Inputs: direction (required).
transferA
Move playback to a Spotify Connect device by name (case-insensitive partial match, e.g. a Sonos room like 'kitchen'). Returns now_playing.
Inputs: device (required), play.
volumeA
Set Spotify volume on the active device: absolute level (0-100) or relative delta. Returns now_playing.
Inputs: delta, level.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Most tools target a distinct action+resource: search resolves names, play starts playback, play_mood plays by mood, add_to_playlist vs create_playlist are clearly separated. The main overlap is play vs play_mood (both start playback, one by track name and one by mood), but the descriptions make the boundary reasonably clear.
There is a readable verb_noun core (add_to_playlist, play_mood, launch_app, list_devices, list_playlists, create_playlist, export_playlists), but it is mixed with bare verbs and nouns (play, skip, search, transfer, volume, now_playing, pause_resume). The conventions are inconsistent, though each name is still understandable.
15 tools is at the top of the well-scoped range but each one covers a distinct capability: playback control, device management, search, and playlist read/write/export. Nothing feels redundant or padded for a Spotify control server.
Core workflows (search, play, device transfer, playlist listing/creation/export) are covered, but there are notable gaps: no remove-from-playlist or delete-playlist, no queue management, no seek/shuffle/repeat, and no save/like track. These omissions will force agents to work around common playlist-editing and playback-control tasks.
Maintenance
Related MCP Connectors
Full Spotify Web API coverage - albums, artists, playlists, player controls, and more.
Spotify MCP server for ChatGPT, Claude and any AI agent: search songs and artists, list playlists, read playlist songs, create playlist, add songs to playlist, remove songs from playlist, set playlist public or private and save to Liked Songs in your own Spotify account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Spotify yourself; Cotlet does not store your password and you need no Spotify API key. About the official Spotify API: Spotify has a full Web API and, since 23 Apr 2026, an official connector for Claude (checked 5 Nov 2026). The API needs an app you register, and in development mode the app owner must have Premium and the app allows 5 users; unlimited users need a registered business with at least 250,000 monthly users. Setup and FAQ: https://cotlet.dev/integrations/spotify-api-mcp-server
Spotify MCP — Web API via client_credentials OAuth
OAuth 2.1 short-link tools for AI agents with scoped tokens, approvals, audit logs, and revocation.
Related MCP Servers
- FlicenseNot gradedqualityBmaintenanceEnables agents to interact with Ethereum, Base and configurable EVM chains over stdio using the shared command catalog, covering contract reads, prepared and policy-guarded execution, wallet management, Socket swaps and bridging, simulation, monitoring and saved contracts.-
- FlicenseNot gradedqualityAmaintenanceExposes an OAuth-gated suite of 38 tools that let web-based AI chat clients securely operate a local machine, covering files, shell, search, Git, SQLite, browser automation, DevTools, background tasks, localhost services, clipboard, notifications, ports, and Postman. A strict command whitelist and configurable folder allowlist keep that broad local access governed rather than unrestricted.-
- FlicenseNot gradedqualityAmaintenanceExposes 38 OAuth-gated tools over one MCP endpoint so web-based AI clients like Claude, ChatGPT, and Grok can read and edit local files, run whitelisted shell commands, search content, use Git, SQLite, browser automation, DevTools, clipboard, notifications, ports, and background jobs on your own machine. A strict command whitelist and folder restrictions keep the local operating surface governable and safe by default.-
- AlicenseNot gradedqualityAmaintenanceExposes an OAuth-gated suite of 38 tools that let web-based AI chat clients operate a local machine, covering files, whitelisted shell commands, search, Git, SQLite, browser and DevTools automation, background tasks, localhost services, clipboard, and ports. It keeps access governed through folder allowlists, a command whitelist, and rate limits so clients gain a large operating surface without unrestricted shell access.MIT