Spotify Playlist MCP

A local STDIO MCP server for safely curating Spotify playlists from Codex desktop scheduled tasks. It can inspect owned playlists, search Spotify tracks, update playlist metadata, and add or remove tracks through a bounded plan/apply workflow.

Safety model

• Reads Spotify credentials and safety settings only from this project's ignored .env, with optional process-level overrides.
• Stores the OAuth token at ~/.config/spotify-playlist-mcp/token.json with file mode 0600.
• Refuses every write unless the playlist ID appears in SPOTIFY_ALLOWED_PLAYLIST_IDS.
• Verifies that the authenticated user owns the playlist.
• Caps each plan with SPOTIFY_MAX_CHANGES_PER_PLAN, default 10 affected tracks.
• Binds plans to the current Spotify snapshot_id, expires them after 10 minutes, and permits one application only.
• Consumes a plan before the first write so a partially applied operation cannot be retried accidentally.

Spotify refresh tokens currently expire six months after authorization. spotify_auth_status reports the remaining time so a scheduled task can warn before reauthorization is required. See Spotify's refresh-token guide.

Tools

Tool	Type	Purpose
spotify_auth_status	Read	Report authorization and refresh-token age without returning credentials
spotify_list_owned_playlists	Read	List owned playlists, visibility, counts, snapshots, and links
spotify_search_tracks	Read	Search for candidate tracks, maximum 10 results per request
spotify_get_playlist	Read	Return current playlist metadata and playable track items
spotify_plan_playlist_changes	Read	Validate and preview additions, removals, name, description, or visibility changes
spotify_apply_playlist_plan	Write	Apply one exact, unexpired, single-use plan

Track additions are appended. URI removals remove every matching occurrence, and the impact count reflects that behavior. The server intentionally does not expose bulk replacement, arbitrary requests, playlist deletion, or unplanned writes.

Install and verify

source ~/.nvm/nvm.sh
nvm use 24.14.0
npm install
npm test
npm run typecheck
npm run build
npm audit

One-time Spotify authorization

The redirect URI in .env must exactly match the Spotify Dashboard setting. The current loopback callback is http://127.0.0.1:3000/auth/callback.

npm run auth

Open the printed Spotify URL and approve the scopes. The command receives the loopback callback and saves the token privately. Check status without revealing credentials:

node dist/auth-cli.js --status

Spotify currently requires reauthorization every six months because refreshing an access token does not extend the refresh token lifetime.

Codex desktop configuration

The desktop app, CLI, and IDE extension share ~/.codex/config.toml. A scheduled desktop task can launch this STDIO server directly:

[mcp_servers.spotify-playlists]
command = "/absolute/path/to/node"
args = ["/absolute/path/to/spotify-playlist-mcp/dist/index.js"]
cwd = "/absolute/path/to/spotify-playlist-mcp"
enabled = true
required = true
default_tools_approval_mode = "auto"
tool_timeout_sec = 60

[mcp_servers.spotify-playlists.env]
SPOTIFY_ALLOWED_PLAYLIST_IDS = "replace-with-owned-playlist-id"
SPOTIFY_MAX_CHANGES_PER_PLAN = "10"

[mcp_servers.spotify-playlists.tools.spotify_apply_playlist_plan]
approval_mode = "approve"

Restart the ChatGPT desktop app after changing MCP configuration. Keep the computer on and the app running when a scheduled task needs the local server. See the official Codex MCP configuration and scheduled tasks documentation.

Leave SPOTIFY_ALLOWED_PLAYLIST_IDS empty until the intended public playlist exists and its exact ID has been reviewed. Multiple IDs may be comma-separated.

Suggested scheduled-task prompt

Use the Spotify playlist MCP to curate only the configured allowlisted playlist.
First check spotify_auth_status and stop with a warning when authorization is missing or due within 14 days.
Inspect the current playlist before searching for candidates.
Follow the playlist's stated audience and description.
Do not remove protected anchor tracks unless the task prompt explicitly names them.
Make no more than the configured change cap.
Create a playlist change plan, report its additions, removals, metadata updates, and warnings, then apply that exact plan only when it matches these rules.
Report the final snapshot ID and Spotify link.

Test this prompt manually before scheduling it. Scheduled runs are unattended, so the mutation tool must not be configured to prompt for approval.

Development

npm test
npm run typecheck
npm run build

Tests use in-memory Spotify fakes and an in-memory MCP transport. No test calls Spotify or reads the real token file.

License

MIT