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.

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

Related MCP server: spotify-mcp

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.

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/<version> user agent.

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