Spotify Music MCP
A local MCP server for Spotify listening context, music discovery, playlists, and playback.
Authentication
The server uses Spotify Authorization Code with PKCE. The existing token location is
~/.config/spotify/token.json; spotify-music-mcp auth login writes to that location and both the
CLI and MCP use the same path. Token values are never returned by tools.
After the package is published on PyPI, install it persistently with uv and run the
connector. It checks the token, refreshes it if needed, prompts for login or new
permissions, verifies the Spotify connection, and configures a supported MCP client:
uv tool install spotify-music-mcp
spotify-music-mcp connect
For a one-time run without persistent installation:
uvx spotify-music-mcp connect
After publication, a pip installation can also run the connector directly:
py -m pip install spotify-music-mcp
spotify-music-mcp connect
For development from a cloned checkout, run uv sync followed by
uv run spotify-music-mcp connect; the generated MCP entry points back to that checkout.
Restart the selected MCP client when setup finishes. You can inspect auth state with
spotify-music-mcp auth status, or run spotify-music-mcp auth login to sign in or grant scopes
manually. Access tokens refresh automatically when possible. Playback control and
queueing require a Spotify Premium account and an active Spotify device.
MCP tools
| Tool | Purpose |
|---|---|
auth_status |
Read authentication state without exposing credentials |
whoami |
Read the current user's profile |
get_recently_played |
Read recent listening history, up to 50 items |
get_top_items |
Read top artists or tracks by time range |
get_saved_tracks |
Read a page of saved tracks |
search_catalog |
Find tracks and their Spotify URIs |
discover_by_genre |
Search tracks by genre, optional keywords, and year range |
find_underground_music |
Search matching low-popularity and broader albums, then retrieve their tracks |
get_artist_new_releases |
Read an artist's albums, singles, and compilations |
get_album_tracks |
Read tracks from an album |
get_user_playlists |
List the current user's playlists |
get_playlist_tracks |
Read a page of playlist items |
create_playlist |
Create a private playlist by default |
add_to_playlist |
Add track IDs or Spotify URIs to a playlist |
get_currently_playing |
Read the current playback item |
add_to_queue |
Queue a track on the active device |
start_playback |
Start a playlist context or track list on an active device |
Paged tools accept limit and offset where applicable. Search results and playlist
items include Spotify IDs or URIs for use by the playlist and playback tools.
Example: Japanese rock discovery
You can ask your assistant for a mix that builds on your listening history while adding artists you have not heard before:
Find me Japanese rock. Make around 30% of the picks new-to-me artists, and don't limit the recommendations to anime soundtracks. Save the results to a private playlist.
An example result is 日本語ロック — 30% new blood: 33 tracks in a private playlist, including 11 picks from new-to-you artists. The rest draw on familiar Japanese rock artists and deeper cuts. Representative new discoveries included:
- SiM — “The Rumbling”
- coldrain — “MAYDAY”
- Crossfaith — “Monolith”
- BAND-MAID — “DOMINATION”
- Vaundy — “Kaiju no Hanauta”
The assistant can use listening history and top-item tools to establish context, search for tracks that match the requested genre and vibe, then create a playlist and add the selected Spotify track URIs.
Example: research-informed study playlist
The Spotify MCP can also build a playlist from recommendations the assistant develops after doing research:
Research whether listening to music while studying affects focus or test scores. Use the evidence carefully, find recordings used in the studies plus suitable instrumental tracks, and put them in a private playlist.
In one example, the assistant created a private playlist with 35 tracks and an estimated runtime of about 2 hours 50 minutes. The assistant handled the research; the Spotify MCP provided the catalog search and playlist tools. Private playlist links are account-specific and should not be copied into public documentation.
Metadata
Release files for spotify-music-mcp 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| spotify_music_mcp-0.1.0.tar.gz | 12.6 kB | Without provenance | Details for spotify_music_mcp-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| spotify_music_mcp-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for spotify_music_mcp-0.1.0-py3-none-any.whl |
Total release size: 28.0 kB
Release files / spotify_music_mcp-0.1.0.tar.gz
| Download URL | spotify_music_mcp-0.1.0.tar.gz |
|---|---|
| Size | 12.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2345fcbf398e082ef843a1226b664d2e9d073fac53c76950c29c5f25627d65a1
|
|
BLAKE2b-256 checksum How to use checksums |
fe9a4ca3241fee1a9ed369a62bc6f546c016c840a7e485f886c30650e3499957
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.14 {"installer":{"name":"uv","version":"0.12.14","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / spotify_music_mcp-0.1.0-py3-none-any.whl
| Download URL | spotify_music_mcp-0.1.0-py3-none-any.whl |
|---|---|
| Size | 15.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c5c05f512365f6566589e78e1b0b3e22dff0461a8218bc5ac56f86c4dcbddf81
|
|
BLAKE2b-256 checksum How to use checksums |
1dbe1a2c8b18165c664fae62fe413340f8a58f3ddb6dba70c8943361d64d13aa
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.14 {"installer":{"name":"uv","version":"0.12.14","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for spotify-music-mcp 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.