Spotify Data

Spotify 数据 MCP 服务

一个 MCP 服务，让 AI 助手（Claude Desktop、 Claude Code、Cursor、VS Code 和其他 MCP 客户端）查询 Spotify 数据：歌曲播放 次数、艺人月听众数、全球排名和热门城市、各国家/地区的 Top 200 和病毒榜单、 包含单曲播放次数的专辑和播放列表、搜索、ISRC 查询，以及流派、 情绪和 BPM。

它在你的电脑上运行，并使用你自己的 API 密钥调用 CheckLeaked Spotify Data API。 免费试用密钥无需银行卡。分步指南： 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

非官方项目。与 Spotify 无关，也未获得 Spotify 的认可或赞助。 Spotify 是 Spotify AB 的商标。

试试这样提问

• “Bad Bunny 和 Karol G 的月听众数是多少？”
• “给我这张专辑中每首单曲的播放次数： https://open.spotify.com/album/3RQQmkQEvNCY4prGKE6oc5”
• “显示巴西今天的 Top 200，只列出前 20 名。”
• “Taylor Swift 哪些城市的听众最多？”
• “比较 Blinding Lights 和 Bohemian Rhapsody 的播放量。”
• “按播放次数排序，列出 Today's Top Hits 的前 30 首单曲及其播放次数。”
• “The Weeknd 的音乐有哪些流派、情绪和 BPM？”
• “哪首 Spotify 单曲的 ISRC 是 USUG11904206？”
• “哪些艺人与 Rosalía 相关？分别有多少月听众？”

1. 获取 API 密钥

每位用户都需要自己的密钥。选择一种方式：

选项	费用	获取地址	SPOTIFY_API_PROVIDER
免费试用：7 天内可发送 500 次请求，无需银行卡	免费	spotify.checkleaked.cc/pricing#trial	direct（自动检测）
RapidAPI 上的 spotify81 接口	免费 Basic 套餐，另有付费套餐	rapidapi.com/airaudoeduardo/api/spotify81	rapidapi（默认）
直接付费密钥	价格见定价页面	spotify.checkleaked.cc/pricing	direct（自动检测）

spotify.checkleaked.cc 发放的密钥（以 sapi_ 开头）会自动发送至 direct API；其他密钥均视为 RapidAPI 密钥。只有在需要覆盖默认设置时，才设置 SPOTIFY_API_PROVIDER。

2. 添加到 MCP 客户端

该服务发布在 PyPI 上，通过 uvx 运行（属于 uv 的一部分；使用 pip install uv 安装，或参阅 uv 安装指南）。首次使用时，uvx 会将软件包下载到缓存的隔离环境中。请在下面的代码片段中将 your-api-key 替换为你的密钥。

无需安装：托管服务（Claude.ai、ChatGPT、任何远程 MCP 客户端）

相同的 12 个工具，以及供 ChatGPT 使用的 fetch 工具，也托管在 https://spotify-proxy.checkleaked.cc/mcp（Streamable HTTP）上。它接受上述任意密钥：来自 spotify.checkleaked.cc 的密钥（以 sapi_ 开头）用于直接 API，其他密钥则用于 RapidAPI 的 spotify81 listing，因此 RapidAPI 订阅也可使用。在 URL 中添加 &provider=direct 或 &provider=rapidapi 即可选择。

• Claude.ai（设置 → 连接器 → 添加自定义连接器）和 ChatGPT（设置 → 连接器；也可用于深度研究，该功能会调用其 search 和 fetch 工具）无法发送自定义请求头，因此请将密钥放入 URL： https://spotify-proxy.checkleaked.cc/mcp?key=your-api-key。请像保护密码一样保护此 URL。

• 能够发送请求头的客户端，请使用 https://spotify-proxy.checkleaked.cc/mcp，并设置 Authorization: Bearer your-api-key。使用 Claude Code 时：

  claude mcp add --transport http spotify-data https://spotify-proxy.checkleaked.cc/mcp --header "Authorization: Bearer your-api-key"
  

每次工具调用都会消耗一个密钥请求额度，与直接调用 API 一样。

Claude Desktop

编辑 claude_desktop_config.json（设置 > 开发者 > 编辑配置；macOS： ~/Library/Application Support/Claude/claude_desktop_config.json，Windows： %APPDATA%\Claude\claude_desktop_config.json），然后重启 Claude Desktop：

{
  "mcpServers": {
    "spotify-data": {
      "command": "uvx",
      "args": ["checkleaked-spotify-mcp"],
      "env": {
        "SPOTIFY_API_KEY": "your-api-key"
      }
    }
  }
}

如果 Claude Desktop 找不到 uvx，请在 command 中填写其完整路径（在 macOS / Linux 上运行 which uvx，或在 Windows 上运行 where uvx）。

Claude Code

claude mcp add spotify-data -s user -e SPOTIFY_API_KEY=your-api-key -- uvx checkleaked-spotify-mcp

Cursor

添加到 ~/.cursor/mcp.json（所有项目）或 .cursor/mcp.json（单个项目）：

{
  "mcpServers": {
    "spotify-data": {
      "command": "uvx",
      "args": ["checkleaked-spotify-mcp"],
      "env": {
        "SPOTIFY_API_KEY": "your-api-key"
      }
    }
  }
}

VS Code（GitHub Copilot Agent 模式）

添加到 .vscode/mcp.json。VS Code 会询问一次密钥，并安全地保存：

{
  "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}"
      }
    }
  }
}

任何其他 MCP 客户端

在环境中设置 SPOTIFY_API_KEY，运行 uvx checkleaked-spotify-mcp（stdio 传输）。如果没有 uvx：运行 pip install checkleaked-spotify-mcp，然后运行 checkleaked-spotify-mcp（或 python -m checkleaked_spotify_mcp）。

Docker

同一服务也以容器镜像形式发布（linux/amd64 和 linux/arm64）：

docker run -i --rm -e SPOTIFY_API_KEY=your-api-key ghcr.io/eduair94/spotify-data-mcp

在客户端配置中，使用 "command": "docker"，并设置 "args": ["run", "-i", "--rm", "-e", "SPOTIFY_API_KEY", "ghcr.io/eduair94/spotify-data-mcp"]， 同时在 env 下设置 SPOTIFY_API_KEY。保留 -i：该服务通过 stdin 和 stdout 使用 MCP 通信。

配置

变量	必需	描述
SPOTIFY_API_KEY	是	你的 API 密钥（见上文）。
SPOTIFY_API_PROVIDER	否	rapidapi（RapidAPI spotify81.p.rapidapi.com）或 direct（https://spotify-proxy.checkleaked.cc/spotify-data）。默认值：根据密钥自动检测。
SPOTIFY_API_BASE	否	覆盖所选提供商的基础 URL。

没有密钥时，服务仍会启动，并且每个工具都会返回错误，说明如何获取免费密钥，因此你可以在聊天中了解问题所在。

工具

所有工具均为只读。每个 id 参数都接受裸 id、spotify: URI 或 open.spotify.com URL（可带或不带 /intl-xx/ 和 ?si=）。

工具	返回内容	批量数量	请求数
search	匹配查询的曲目、艺人、专辑或播放列表，包含 id 和 URL（曲目可选返回播放次数）	最多 20 条	1
get_tracks	曲目详情：艺人、专辑、发行日期、时长、ISRC、热度、播放次数；可选流派／情绪／BPM／制作人员信息	50 首曲目	1
get_track_play_count	累计播放次数，以及名称、艺人、发行日期	50 首曲目	1
get_track_insights	流派、情绪、活动（含权重）、BPM、制作人员信息、歌词标记、语言	50 首曲目	1
get_artists_stats	月听众数、关注者数、世界排名、热度、流派、前 5 个城市	50 位艺人	1
get_artist_overview	艺人资料，含统计数据、带播放次数的热门曲目、最新发行作品、唱片目录数量、相关艺人、简介、链接	1 位艺人	1
get_artist_insights	根据艺人的热门曲目生成的流派、情绪和节奏概况	20 位艺人	1
get_related_artists	“粉丝也喜欢”的艺人	1 位艺人	1
get_album	专辑详情及每首曲目的播放次数，还有专辑总播放次数	1 张专辑	1
get_playlist	名称、所有者、关注者、描述，以及每页最多 100 首带播放次数的曲目	100 首曲目	首页 2 次，之后每页 1 次
get_chart	某个国家的 Top 200、热门榜、热门艺人或热门专辑（日榜或周榜，可选最新榜单或指定日期），可选播放次数	最多 200 条	1
isrc_lookup	ISRC 对应的 Spotify 曲目	1 个 ISRC	1

输出为精简 JSON：id、名称、数字和 open.spotify.com URL，列表会限制长度， 以便适配模型的上下文。注意：

• 对播放次数少于 1,000 的曲目，Spotify 显示的播放次数为 0。
• 播放次数为累计播放量；榜单中的 streams 是该榜单对应日或周的播放量。
• API 可能会缓存结果一段时间（播放次数约缓存一小时）。
• API 的歌词、音频下载、webhook、跟踪和 AI 端点均不会对外开放。

隐私

此服务只会与您配置的 API 通信（RapidAPI 的 spotify81.p.rapidapi.com 或 spotify-proxy.checkleaked.cc）。它会在 x-rapidapi-key 标头中发送您的密钥，不会在磁盘上存储任何内容，也不会收集遥测数据。请求会携带 checkleaked-spotify-mcp/<version> 用户代理。

托管服务会将每次工具调用转发到使用您密钥的同一 API，且不会保留对话数据。放在 URL 中的密钥可能会像其他 URL 一样出现在请求日志中，因此如果客户端支持，请优先使用 Authorization 标头。

开发

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

基于官方 MCP Python SDK 和 checkleaked-spotify-api SDK 构建。 API 参考：spotify-proxy.checkleaked.cc/docs。 服务状态：spotify.checkleaked.cc/status。

许可证

MIT