Skip to main content

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)

Source distribution for spotify-music-mcp 0.1.0
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)

Table of built distributions (wheels) for spotify-music-mcp 0.1.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page