Spotify Data

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-mcp

Unofficial. 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?"

1. Get an API key

Every user needs their own key. Pick one:

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 search and fetch tools) 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/mcp with Authorization: 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-mcp

Cursor

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-mcp

In 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

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=).

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 streams are 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/ 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 test

Built 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

MIT