Skip to main content
Glama
Spotify Data MCP Server

Spotify Data MCP Server

Spotify Data MCP Server

PyPI Python License: MIT

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

Related MCP server: spotifyMCP

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

Available Tools

12 tools
get_albumGet albumB
Read-onlyIdempotent
Inspect

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 BPMA
Read-onlyIdempotent
Inspect

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 overviewB
Read-onlyIdempotent
Inspect

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 statsB
Read-onlyIdempotent
Inspect

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 chartsA
Read-onlyIdempotent
Inspect

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 playlistA
Read-onlyIdempotent
Inspect

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 BPMB
Read-onlyIdempotent
Inspect

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 countsA
Read-onlyIdempotent
Inspect

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 tracksA
Read-onlyIdempotent
Inspect

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 ISRCA
Read-onlyIdempotent
Inspect

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 12 tools

    Disambiguation3/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables interaction with Spotify through MCP, providing tools for searching tracks, artists, albums, playlists, and accessing user data like top tracks and recently played.
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables controlling Spotify playback, managing playlists, searching music, and accessing library features through any MCP-compatible AI client. Provides 34 tools for full Spotify integration.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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