spotify-dj MCP

A Spotify DJ MCP server: real DJ metadata plus full playlist control, in one local server. Spotify removed audio-features in 2024, so pure Spotify MCPs cannot give BPM anymore. This one rebuilds it from free sources, with per-field provenance, and pairs it with staged playlist writes.

What it does

• DJ metadata for any track: BPM, key plus Camelot, energy, danceability, valence. Multi-tier free chain (cache, ReccoBeats, Deezer, AcousticBrainz, TheAudioDB, optional local analysis), every value tagged with provider.

• Transition scoring 0-100 (harmonic plus octave-aware tempo plus energy), next-track suggestions, energy-arc setlist planning, Rekordbox-friendly export.

• Full Spotify control: search, playlists (list, read, create, edit, add, remove, reorder with snapshot rollback), playback, queue, devices, library, top items, history.

• Safety first: every stored-data mutation stages a preview with an operation_id, then a single-use commit revalidates before applying. Writes need resolved Spotify IDs, never guesses.

Related MCP server: Heavenly Health Protocol

Quick start

Requires Python 3.14, a Spotify account with Premium (app owner), and uv.

git clone https://github.com/cikeyz/spotify-dj.git
Set-Location spotify-dj
uv venv --python 3.14
.\.venv\Scripts\Activate.ps1
uv pip install -r requirements.txt

Create a Spotify app (2 min, free): open the dashboard, Create app, add exactly http://127.0.0.1:8888/callback to Redirect URIs, check Web API only, then add yourself under User Management. Copy the Client ID, then:

$env:SPOTIFY_DJ_HOME = "$env:LOCALAPPDATA\spotify-dj"
.\.venv\Scripts\python.exe setup\setup.py --client-id '<your-client-id>'
.\.venv\Scripts\python.exe setup\setup.py --auth-url
# open the printed URL, approve, then:
.\.venv\Scripts\python.exe setup\setup.py --auth-code '<pasted-redirect-url>'
.\.venv\Scripts\python.exe setup\tests\verify_server.py

Expect RESULT: ALL CHECKS PASSED. Full walkthrough in docs/SETUP.md.

MCP client config (stdio only)

{
  "mcpServers": {
    "spotify-dj": {
      "command": "C:\\path\\to\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\server.py"],
      "env": { "SPOTIFY_DJ_HOME": "C:\\path\\to\\state" }
    }
  }
}

Launch the .venv Python directly, never through uv's runner. Tokens, cache, and audit logs live in SPOTIFY_DJ_HOME, never in this repo.

Tools (31) and prompts (3)

Prompts: build-set (crate to ordered setlist), audit-crate (drift and duplicate report), organize-playlist (dedupe, sort, split).

Reads return cursor envelopes (items, next_page_token, has_more) capped at 30KB. Mutations stage first, commit once. Details and live API discoveries in docs/ARCHITECTURE.md.

Optional: local analysis tier

Without it the server uses keyless catalogs only. To measure BPM and key from audio as a last resort (proves out at ~5s per track):

.\.venv\Scripts\python.exe -m pip install librosa
$env:SPOTIFY_DJ_LOCAL_ANALYSIS = "1"

Tests

.\.venv\Scripts\python.exe setup\tests\verify_server.py
.\.venv\Scripts\python.exe setup\tests\test_server.py

verify_server.py is offline plus static. test_server.py runs live against your account with self-cleaning SPOTIFYDJ-TEST- playlists and must end with RESULT: ALL CHECKS PASSED and zero residue.

Layout

• server.py: thin shell (tools, registration, stdio entry)

• core.py: state, staged store, Spotify client, envelopes

• playlists.py, collection.py, dj.py, prompts.py: feature modules

• setup/setup.py: PKCE grant, refresh, status

• setup/tests/: verify plus live batteries

• docs/: SETUP.md guide, ARCHITECTURE.md design plus discoveries

Released under the MIT License.