Guide

Spotify MCP server: play counts, monthly listeners and charts in Claude, Cursor and VS Code

An MCP server gives an AI assistant tools it can call. This one gives it 12 read-only tools over this API, so Claude, Cursor, VS Code or any other MCP client answers with Spotify's own numbers: a track's lifetime play count, an artist's monthly listeners and top cities, today's Top 200 in a country. It is open source (MIT), runs on your machine with your own API key, or connects to a hosted endpoint with nothing to install. The free trial key needs no card.

By Eduardo Airaudo, maintainer of the API and the server · Updated 1 November 2026

Get a free key Setup Source on GitHub

What you can ask

The assistant picks the tools and reads their answers; you ask in your own words. Questions like these, most of them from the server's own README:

  • “How many streams does Blinding Lights have?”
  • “What are Bad Bunny's monthly listeners, and which cities listen to him most?”
  • “Show today's Top 200 in Brazil, top 50 only, with each track's play count.”
  • “Give me the play counts of every track on this album: https://open.spotify.com/album/3RQQmkQEvNCY4prGKE6oc5”
  • “What genres, moods and BPM does The Weeknd's music have?”
  • “Who are the artists related to Rosalía, and how many monthly listeners does each have?”

A play count of 0 means fewer than 1,000 plays, the way Spotify reports it. Play counts are lifetime plays; a chart's streams are the plays in that chart's day or week.

Set it up in two minutes

A key, one block of config in your client, and a question. If you would rather install nothing, skip to the hosted endpoint.

1. Get a free key

The trial key is emailed to you: 500 requests over 7 days, no card. A tool call spends one, so that is room for about 500 tool calls.

500 requests over 7 days at 1 request per second, one trial per address, no card. The key comes by email and calls 80 of the 107 endpoints: all but downloads, AI analyses, tracking, webhooks and playlist snapshots.

Already have a key? A paid direct key works the same way, and a RapidAPI key for the spotify81 listing works with the local server and with the hosted endpoint. Keys from this site start with sapi_ and go to the direct API; any other key is sent to RapidAPI. SPOTIFY_API_PROVIDER, set to rapidapi or direct, overrides that.

2. Add the server to your client

The client starts the server in Docker, from the ghcr.io/eduair94/spotify-data-mcp image (linux/amd64 and linux/arm64), so Docker has to be installed and running. Replace your-api-key with your key.

Claude Desktop

Edit claude_desktop_config.json (Settings > Developer > Edit Config; on macOS ~/Library/Application Support/Claude/claude_desktop_config.json, on Windows %APPDATA%\Claude\claude_desktop_config.json), then restart Claude Desktop.

Claude Code

Run it once in a terminal. -s user adds the server for all your projects.

Cursor

Add it to ~/.cursor/mcp.json for all projects, or to .cursor/mcp.json for one.

VS Code (GitHub Copilot agent mode)

Add it to .vscode/mcp.json. VS Code asks for the key once and stores it securely.

Any other client

Any client that starts a stdio server: give it this command, with SPOTIFY_API_KEY in its environment. Keep -i: the server speaks MCP over stdin and stdout.

3. Ask

Restart Claude Desktop if you edited its config, then ask one of the questions above. A missing key shows up in the chat too: the server still starts, and every tool answers with an error that says where to get a free one.

No install: the hosted endpoint

The API's own host serves read-only Spotify tools over MCP's Streamable HTTP transport at https://spotify-proxy.checkleaked.cc/mcp. Nothing runs on your machine. It takes a direct or trial key from this site or a RapidAPI key for spotify81, and each tool call spends one request of it. Besides the tools below it has fetch, the tool ChatGPT's connectors and deep research use to read a search result.

Claude.ai, ChatGPT and other connectors that take a URL

Add a custom connector and give it this URL, with your key in place of your-api-key. The key travels in the URL, so keep the URL as private as the key: anyone who has it can spend your requests.

Clients that send a header

Claude Code, Cursor and VS Code send the key in the Authorization header instead, so it stays out of the URL.

The 12 tools

All read-only. Every id parameter takes a bare id, a spotify: URI or an open.spotify.com URL. Answers are compact JSON — ids, names, numbers and links, with lists capped — so they fit in the model's context.

search
Tracks, artists, albums or playlists matching a query, with ids and URLs, optionally with play counts for tracks.Up to 20 hits a call · 1 request
get_tracks
Track details: artists, album, release date, duration, ISRC, popularity and play count, optionally genres, moods, BPM and credits.50 tracks a call · 1 request
get_track_play_count
Lifetime play counts, with name, artists and release date.50 tracks a call · 1 request
get_track_insights
Genres, moods and activities with their weights, BPM, credits, a lyrics flag and languages.50 tracks a call · 1 request
get_artists_stats
Monthly listeners, followers, world rank, popularity, genres and the top 5 cities.50 artists a call · 1 request
get_artist_overview
Profile with stats, top tracks with play counts, latest release, discography counts, related artists, biography and links.1 artist a call · 1 request
get_artist_insights
Genre, mood and tempo profile from the artist's top tracks.20 artists a call · 1 request
get_related_artists
The artists Spotify lists under Fans also like.1 artist a call · 1 request
get_album
Album details and every track with its play count, plus the album total.1 album a call · 1 request
get_playlist
Name, owner, followers, description and up to 100 tracks a page with play counts.100 tracks a call · 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, optionally with play counts.Up to 200 entries a call · 1 request
isrc_lookup
The Spotify tracks for an ISRC.1 ISRC a call · 1 request

Lyrics, audio downloads, webhooks, tracking and the AI analyses are not among them. Results can come from the API's cache, play counts up to about an hour old.

What a question costs

A tool call spends requests from your key, as calling the API yourself would: one a call, except get_playlist, which spends two on its first page. A question can take several calls, a search to find the track and then its play count, so count calls rather than questions.

The batch tools stretch a request: get_track_play_count takes 50 tracks in one call. Calls also count against your key's rate limit, the same as any other request.

  • Free trial

    Up to 500 tool calls

    over 7 days, no card

    Or play counts for up to 25,000 tracks at 50 a call. 1 request a second.

  • Direct pack · $9

    Up to 20,000 tool calls

    credits valid 120 days

    The smallest pack. A direct key includes 10 requests a second.

  • RapidAPI Basic · $0

    Up to 1,000 tool calls

    a month

    Local server or the hosted endpoint. 5 requests a second on every RapidAPI plan.

Every direct pack, up to 10M requests, is on the pricing page.

Privacy: your key stays with you

  • The local server runs on your machine and talks only to the API you configure, spotify-proxy.checkleaked.cc or RapidAPI's spotify81.p.rapidapi.com. It sends your key there in the x-rapidapi-key header, as any call to the API does, stores nothing on disk and has no telemetry.
  • With the local server, your key sits in your client's config or environment, not in the conversation: the model sees what the tools return, never the key.
  • There is no Spotify login. No tool reads or changes a Spotify account; they return public catalogue, chart and play-count data.
  • What a tool returns becomes part of your conversation, so your AI provider sees it like any other message.
  • The hosted endpoint receives your key with every call, on spotify-proxy.checkleaked.cc, the host that serves the API. In the URL form, the service you add the connector to keeps the URL, key included.

Questions

Is this an official Spotify MCP server?

No. It is an open-source server (MIT licence) by the maintainer of this API, which is an independent commercial service, not affiliated with or endorsed by Spotify. The server reads Spotify data through this API with your key. Its name in the official MCP Registry is cc.checkleaked/spotify-data.

Do I need a Spotify account or a Spotify developer app?

No. There is no Spotify login and no OAuth flow: the server needs one API key, from this site or for RapidAPI's spotify81 listing, in SPOTIFY_API_KEY. Every tool is read-only.

Does a RapidAPI key work?

Yes. Keys from this site start with sapi_ and go to the direct API; any other key is treated as a RapidAPI key, and with the local server SPOTIFY_API_PROVIDER (rapidapi or direct) overrides that. The hosted endpoint sorts keys the same way; add &provider=direct or &provider=rapidapi to its URL to choose.

How many requests does a question use?

One per tool call, except get_playlist, which spends two on its first page. A question can take several calls, so the free trial's 500 requests are about 500 tool calls, and batch tools such as get_track_play_count take up to 50 tracks in one.

What are the rate limits?

Your key's own, as for any request: 1 request a second on the free trial, 10 on a direct key and 5 on RapidAPI.

What data can it return?

Track play counts (0 means fewer than 1,000), artists' monthly listeners, followers, world rank and top cities, Top 200, viral, top artist and top album charts by country, albums and playlists with per-track play counts, search, ISRC lookup, and genres, moods and BPM. Lyrics, audio downloads, webhooks, tracking and the AI analyses are not exposed. Results can come from the API's cache, play counts up to about an hour old.

Which MCP clients does it work with?

Any client that starts a local server over stdio, Claude Desktop, Claude Code, Cursor and VS Code among them. Clients that connect to a remote URL, such as custom connectors in Claude.ai and ChatGPT, use the hosted endpoint.

Can I run it without Docker?

Yes. Clone https://github.com/eduair94/spotify-data-mcp and install it with pip (pip install .), then give your client checkleaked-spotify-mcp as the command in place of docker, with no args and SPOTIFY_API_KEY in its environment. Use its full path if the client cannot find it. The hosted endpoint needs no install at all.

Sources

More guides

What changed in the API and on these pages, and when: What's new.

Get a key, then ask your first question

The free trial covers 500 tool calls over 7 days. After that, a direct pack is 20K requests for $9, credits valid 120 days, and a RapidAPI spotify81 key works with the local server.

Direct Portal Source on GitHub API reference

Not ready to buy? Get a free trial key: 500 requests over 7 days, no card.