Spotify Data MCP Server
Looks up Spotify data via the CheckLeaked Spotify Data API: track lifetime play counts (batch up to 50), artist monthly listeners, followers, world rank and top cities, artist overviews with top tracks, discography and related artists, albums and playlists with per-track play counts and totals, Top 200/viral/top artist/top album charts by country (daily or weekly, by date), track insights (genres, moods, activities, BPM, credits, languages), search across tracks, artists, albums and playlists, and ISRC lookup. Accepts bare ids, spotify: URIs or open.spotify.com URLs.
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., "@Spotify Data MCP Server What are the monthly listeners of Bad Bunny and Karol G?"
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.
Spotify Data MCP Server
An MCP server that lets AI assistants (Claude Desktop, Claude Code, Cursor, VS Code and other MCP clients) look up Spotify data: track play counts, artist monthly listeners, world rank and top cities, Top 200 and viral charts by country, albums and playlists with per-track play counts, search, ISRC lookup, and genres, moods and BPM.
It runs on your machine and calls the CheckLeaked Spotify Data API with your own API key. A free trial key needs no card. Step-by-step guide: spotify.checkleaked.cc/spotify-mcp-server.
uvx checkleaked-spotify-mcp
# or, with Docker
docker run -i --rm -e SPOTIFY_API_KEY=your-api-key ghcr.io/eduair94/spotify-data-mcpUnofficial. Not affiliated with, endorsed by or sponsored by Spotify. Spotify is a trademark of Spotify AB.
Ask things like
"What are the monthly listeners of Bad Bunny and Karol G?"
"Give me the play counts of every track on this album: https://open.spotify.com/album/3RQQmkQEvNCY4prGKE6oc5"
"Show today's Top 200 in Brazil, top 20 only."
"Which cities listen to Taylor Swift the most?"
"Compare the streams of Blinding Lights and Bohemian Rhapsody."
"List the first 30 tracks of Today's Top Hits with their play counts, sorted by plays."
"What genres, moods and BPM does The Weeknd's music have?"
"Which Spotify track has the ISRC USUG11904206?"
"Who are the artists related to Rosalía, and how many monthly listeners does each have?"
Related MCP server: spotifyMCP
1. Get an API key
Every user needs their own key. Pick one:
Option | Cost | Where |
|
Free trial: 500 requests over 7 days, no card | Free |
| |
RapidAPI listing | Free Basic plan, paid tiers |
| |
Direct paid key | From the pricing page |
|
Keys issued by spotify.checkleaked.cc (they start with sapi_) are sent to the direct API
automatically; any other key is treated as a RapidAPI key. Set SPOTIFY_API_PROVIDER only
to override that.
2. Add it to your MCP client
The server is published on PyPI and runs with uvx (part of
uv; install it with pip install uv or see the
uv install guide). uvx
downloads the package into a cached, isolated environment on first use. Replace
your-api-key with your key in the snippets below.
No install: the hosted server (Claude.ai, ChatGPT, any remote MCP client)
The same 12 tools, plus a fetch tool for ChatGPT, are also hosted at https://spotify-proxy.checkleaked.cc/mcp (Streamable
HTTP). It takes any of the keys above: keys from spotify.checkleaked.cc (they start with sapi_)
are spent on the direct API, and any other key on RapidAPI's spotify81 listing, so a RapidAPI
subscription works too. Add &provider=direct or &provider=rapidapi to the URL to choose.
Claude.ai (Settings → Connectors → Add custom connector) and ChatGPT (Settings → Connectors; also usable in deep research, which calls its
searchandfetchtools) cannot send custom headers, so put the key in the URL:https://spotify-proxy.checkleaked.cc/mcp?key=your-api-key. Treat that URL like a password.Clients that can send headers use
https://spotify-proxy.checkleaked.cc/mcpwithAuthorization: Bearer your-api-key. With Claude Code:claude mcp add --transport http spotify-data https://spotify-proxy.checkleaked.cc/mcp --header "Authorization: Bearer your-api-key"
Each tool call spends one request of your key, as a direct API call would.
Claude Desktop
Edit claude_desktop_config.json (Settings > Developer > Edit Config; macOS:
~/Library/Application Support/Claude/claude_desktop_config.json, Windows:
%APPDATA%\Claude\claude_desktop_config.json) and restart Claude Desktop:
{
"mcpServers": {
"spotify-data": {
"command": "uvx",
"args": ["checkleaked-spotify-mcp"],
"env": {
"SPOTIFY_API_KEY": "your-api-key"
}
}
}
}If Claude Desktop cannot find uvx, put its full path in command (run which uvx on
macOS / Linux or where uvx on Windows).
Claude Code
claude mcp add spotify-data -s user -e SPOTIFY_API_KEY=your-api-key -- uvx checkleaked-spotify-mcpCursor
Add to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):
{
"mcpServers": {
"spotify-data": {
"command": "uvx",
"args": ["checkleaked-spotify-mcp"],
"env": {
"SPOTIFY_API_KEY": "your-api-key"
}
}
}
}VS Code (GitHub Copilot agent mode)
Add to .vscode/mcp.json. VS Code asks for the key once and stores it securely:
{
"inputs": [
{
"type": "promptString",
"id": "spotify-api-key",
"description": "Spotify Data API key",
"password": true
}
],
"servers": {
"spotify-data": {
"type": "stdio",
"command": "uvx",
"args": ["checkleaked-spotify-mcp"],
"env": {
"SPOTIFY_API_KEY": "${input:spotify-api-key}"
}
}
}
}Any other MCP client
Run uvx checkleaked-spotify-mcp (stdio transport) with SPOTIFY_API_KEY in its
environment. Without uvx: pip install checkleaked-spotify-mcp, then run
checkleaked-spotify-mcp (or python -m checkleaked_spotify_mcp).
Docker
The same server is published as a container image (linux/amd64 and linux/arm64):
docker run -i --rm -e SPOTIFY_API_KEY=your-api-key ghcr.io/eduair94/spotify-data-mcpIn a client config, use "command": "docker" with
"args": ["run", "-i", "--rm", "-e", "SPOTIFY_API_KEY", "ghcr.io/eduair94/spotify-data-mcp"]
and SPOTIFY_API_KEY under env. Keep -i: the server speaks MCP over stdin and stdout.
Configuration
Variable | Required | Description |
| yes | Your API key (see above). |
| no |
|
| no | Override the base URL of the chosen provider. |
Without a key the server still starts, and every tool answers with an error that says where to get a free key, so you can see what is wrong from inside your chat.
Tools
All tools are read-only. Every id parameter accepts a bare id, a spotify: URI or an
open.spotify.com URL (with or without /intl-xx/ and ?si=).
Tool | What it returns | Batch | Requests |
| Tracks, artists, albums or playlists matching a query, with ids and URLs (optionally play counts for tracks) | up to 20 hits | 1 |
| Track details: artists, album, release date, duration, ISRC, popularity, play count; optional genres / moods / BPM / credits | 50 tracks | 1 |
| Lifetime play counts with name, artists, release date | 50 tracks | 1 |
| Genres, moods, activities (with weights), BPM, credits, lyrics flag, languages | 50 tracks | 1 |
| Monthly listeners, followers, world rank, popularity, genres, top 5 cities | 50 artists | 1 |
| Profile with stats, top tracks with play counts, latest release, discography counts, related artists, biography, links | 1 artist | 1 |
| Genre, mood and tempo profile from the artist's top tracks | 20 artists | 1 |
| "Fans also like" artists | 1 artist | 1 |
| Album details and every track with its play count, plus the album total | 1 album | 1 |
| Name, owner, followers, description and up to 100 tracks per page with play counts | 100 tracks | 2 on the first page, then 1 |
| Top 200, viral, top artists or top albums for a country (daily or weekly, latest or by date), optional play counts | up to 200 entries | 1 |
| Spotify tracks for an ISRC | 1 ISRC | 1 |
Outputs are compact JSON: ids, names, numbers and open.spotify.com URLs, with lists capped,
so they fit in the model's context. Notes:
Spotify shows a play count of 0 for tracks with fewer than 1,000 plays.
Play counts are lifetime plays; chart
streamsare the plays in that chart's day or week.Results may be cached by the API for a while (play counts about an hour).
Lyrics, audio downloads, webhooks, tracking and AI endpoints of the API are deliberately not exposed.
Privacy
The server only talks to the API you configure (RapidAPI's spotify81.p.rapidapi.com or
spotify-proxy.checkleaked.cc). It sends your key in the x-rapidapi-key header, stores
nothing on disk and has no telemetry. Requests carry a checkleaked-spotify-mcp/<version>
user agent.
The hosted server passes each tool call to the same API with your key and keeps no
conversation data. A key sent in the URL can appear in request logs like any URL, so prefer
the Authorization header where your client supports it.
Development
git clone https://github.com/eduair94/spotify-data-mcp
cd spotify-data-mcp
python -m venv .venv && . .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pytest # offline tests (recorded API answers)
SPOTIFY_MCP_LIVE=1 SPOTIFY_API_KEY=... pytest -m live # optional live smoke testBuilt on the official MCP Python SDK
and the checkleaked-spotify-api SDK.
API reference: spotify-proxy.checkleaked.cc/docs.
Service status: spotify.checkleaked.cc/status.
License
Available Tools
12 toolsget_albumGet albumBRead-onlyIdempotentInspect
An album with its track list and (by default) every track's lifetime play count, plus the album total, release date, label, UPC and popularity.
Inputs: album (required), include_play_counts.
get_artist_insightsArtist genres, moods and BPMARead-onlyIdempotentInspect
An artist's sound profile from their top tracks: genres, moods and activities with 0-1 weights, and tempo (average, min, max BPM). Up to 20 artists per call.
Inputs: artists (required).
get_artist_overviewArtist overviewBRead-onlyIdempotentInspect
One artist's profile: monthly listeners, followers, world rank, top cities, top tracks with play counts, latest release, discography counts, related artists, biography and social links.
Inputs: artist (required), top_tracks.
get_artists_statsArtist monthly listeners and statsBRead-onlyIdempotentInspect
Monthly listeners, followers, world rank, popularity, genres and top 5 cities (with listener counts) for up to 50 artists in one call.
Inputs: artists (required).
get_chartSpotify chartsARead-onlyIdempotentInspect
Spotify Charts by country: top_tracks (Top 200), viral_tracks (Viral 50, daily only), top_artists or top_albums. Each entry has rank, previous and peak rank, days (or weeks) on the chart, movement and, for top_tracks, the streams in that period. Defaults to the latest published daily chart.
Inputs: date, chart, limit, period, +2 more.
get_playlistGet playlistARead-onlyIdempotentInspect
A playlist's name, owner, followers and description, plus limit tracks (max 100) from offset with lifetime play counts. Use next_offset from the answer to page through long playlists (later pages skip the metadata and cost one request).
Inputs: playlist (required), limit, offset, include_play_counts.
get_track_insightsTrack genres, moods and BPMBRead-onlyIdempotentInspect
Genres, moods and activities (with Spotify's 0-1 weights), tempo in BPM, credits (writers, producers), lyrics flag and vocal languages for up to 50 tracks.
Inputs: tracks (required).
get_track_play_countTrack play countsARead-onlyIdempotentInspect
Lifetime Spotify play counts (streams) for up to 50 tracks in one call, with track name, artists and release date. The fastest way to compare streams. A play count of 0 means fewer than 1,000 plays.
Inputs: tracks (required).
get_tracksGet tracksARead-onlyIdempotentInspect
Track details for up to 50 tracks in one call: name, artists, album, release date, duration, explicit flag, popularity, ISRC and (by default) lifetime play count. include_insights adds genres, moods, activities, BPM, credits, lyrics flag and languages. A play count of 0 means fewer than 1,000 plays.
Inputs: tracks (required), include_insights, include_play_counts.
isrc_lookupFind tracks by ISRCARead-onlyIdempotentInspect
Find the Spotify track(s) for an ISRC (International Standard Recording Code), e.g. USUG11904206. Returns ids, names, artists, album and release date.
Inputs: isrc (required).
searchSearch SpotifyARead-onlyIdempotentInspect
Search the Spotify catalog by name to find ids for the other tools. type picks what to search: tracks, artists, albums or playlists. Returns up to limit hits (max 20) with id, name, key fields and open.spotify.com URL. For track searches, include_play_counts adds each hit's lifetime play count.
Inputs: query (required), type, limit, include_play_counts.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
The track tools overlap heavily: get_tracks already returns play counts by default and insights via include_insights, which largely subsumes get_track_play_count and get_track_insights. Similarly get_artist_overview absorbs much of get_artists_stats and get_artist_insights. Descriptions do help (batch vs. single, 'fastest way to compare streams'), but an agent still has to reason about which of several near-duplicate paths to take.
Most tools follow a clear get_<resource> pattern (get_tracks, get_album, get_playlist, get_chart), with two outliers: 'search' (bare verb, no noun) and 'isrc_lookup' (noun_verb reversed). Singular/plural switching (get_tracks vs. get_track_play_count) is slightly irregular but readable and intentional.
Twelve tools is well within the sweet spot and each maps to a concrete Spotify data concept (tracks, artists, albums, playlists, charts, ISRC). Nothing feels padded except arguably the redundant track/artist variants, but the count itself is well scoped.
The surface covers the analytics domain well: discovery via search and isrc_lookup, batch and single lookups across tracks/artists/albums/playlists, plus charts. Minor gaps remain — albums are single-only with no batch counterpart, and there is no way to list an artist's full discography or enumerate playlists, but these are workaroundable.
Maintenance
Related MCP Connectors
Spotify play counts for any track, album, artist or playlist, plus monthly listeners and followers.
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
Free ISRC lookup and public titles for Reels, TikTok, Shorts, and X links.
Music industry tools for AI agents: artist research, catalogs, release plans and content.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables interaction with Spotify through MCP, providing tools for searching tracks, artists, albums, playlists, and accessing user data like top tracks and recently played.-
- FlicenseNot gradedqualityDmaintenanceEnables controlling Spotify playback, managing playlists, searching music, and accessing library features through any MCP-compatible AI client. Provides 34 tools for full Spotify integration.-
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to fetch music artist, album, and track metadata, search tracks, discover similar artists, and list top tracks, tags, charts, and user listening stats through MCP tools.74 npm1MIT
- AlicenseNot gradedqualityBmaintenanceEnables MCP-compatible AI assistants to control Spotify Premium accounts by searching music, managing playback and devices, handling queues, creating and editing playlists, and browsing or modifying the library.MIT