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:

Option	Cost	Where	SPOTIFY_API_PROVIDER
Free trial: 500 requests over 7 days, no card	Free	spotify.checkleaked.cc/pricing#trial	direct (detected automatically)
RapidAPI listing spotify81	Free Basic plan, paid tiers	rapidapi.com/airaudoeduardo/api/spotify81	rapidapi (default)
Direct paid key	From the pricing page	spotify.checkleaked.cc/pricing	direct (detected automatically)

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

Variable	Required	Description
SPOTIFY_API_KEY	yes	Your API key (see above).
SPOTIFY_API_PROVIDER	no	rapidapi (RapidAPI spotify81.p.rapidapi.com) or direct (https://spotify-proxy.checkleaked.cc/spotify-data). Default: detected from the key.
SPOTIFY_API_BASE	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
search	Tracks, artists, albums or playlists matching a query, with ids and URLs (optionally play counts for tracks)	up to 20 hits	1
get_tracks	Track details: artists, album, release date, duration, ISRC, popularity, play count; optional genres / moods / BPM / credits	50 tracks	1
get_track_play_count	Lifetime play counts with name, artists, release date	50 tracks	1
get_track_insights	Genres, moods, activities (with weights), BPM, credits, lyrics flag, languages	50 tracks	1
get_artists_stats	Monthly listeners, followers, world rank, popularity, genres, top 5 cities	50 artists	1
get_artist_overview	Profile with stats, top tracks with play counts, latest release, discography counts, related artists, biography, links	1 artist	1
get_artist_insights	Genre, mood and tempo profile from the artist's top tracks	20 artists	1
get_related_artists	"Fans also like" artists	1 artist	1
get_album	Album details and every track with its play count, plus the album total	1 album	1
get_playlist	Name, owner, followers, description and up to 100 tracks per page with play counts	100 tracks	2 on the first page, then 1
get_chart	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
isrc_lookup	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 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.

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