Skip to main content
Glama

spotify-mcp

一个将 Claude 与 Spotify 连接起来的 模型上下文协议 (MCP) 服务器。通过与 Claude 的自然对话,控制你的 Spotify 播放、搜索音乐、管理播放列表等。

分支说明:本项目派生自 varunneal/spotify-mcp,并针对 2026 年 2 月的 Spotify Web API 变更进行了更新。使用 Claude Code 构建和维护。

更新内容 (v0.4.0)

架构重写

  • 弃用 spotipy -- 直接使用 httpx 异步请求(原生异步,无需 asyncio.to_thread 包装)

  • 单一模块 -- 将 server.py、spotify_api.py、utils.py 合并为一个文件

  • FastMCP -- 使用简洁的 @mcp.tool() 装饰器,而非手动 ToolModel + match/case 路由

  • 2 个依赖项 -- 仅 mcp + httpx(原为 mcp + spotipy + python-dotenv)

  • 显式 OAuth -- 使用 spotify-mcp --auth 进行初始设置,后续使用时自动刷新

功能(保留自 v0.3.0)

  • 开始、暂停和跳过播放

  • 搜索曲目、专辑、艺术家和播放列表

  • 获取有关任何 Spotify 项目的详细信息

  • 管理播放队列

  • 完整的播放列表 CRUD(创建、读取、更新、删除曲目)

  • 获取已点赞/保存的歌曲,并可选择进行流派丰富

  • 适配 Spotify 2026 年 2 月的 API 变更

Related MCP server: Spotify MCP Server

工作原理

Claude <--MCP (stdio)--> spotify-mcp <--httpx async--> Spotify Web API
  1. Claude 通过 MCP 协议发送工具调用

  2. 服务器使用 httpx 将其转换为 Spotify Web API 请求

  3. OAuth 令牌自动刷新;初始认证通过 spotify-mcp --auth 完成

  4. 结果被解析为简洁的 JSON 并返回给 Claude

可用工具

工具

操作

描述

spotify_playback

get, start, pause, skip, previous, volume

控制音乐播放和音量

spotify_search

--

搜索曲目、专辑、艺术家、播放列表

spotify_queue

get, add

查看和管理播放队列

spotify_get_info

--

通过 Spotify URI 获取详细项目信息

spotify_playlist

get, get_tracks, add_tracks, remove_tracks, change_details, create, delete

完整的播放列表管理

spotify_liked_songs

get, get_with_genres, like, unlike, check

管理已保存的歌曲并检查库

spotify_recently_played

--

获取带有时间戳的最近播放曲目

spotify_devices

list, transfer

列出设备并传输播放

架构

src/spotify_mcp/
  __init__.py   # Entry point (stdio / --auth)
  server.py     # FastMCP server, API client, parsers — all in one

先决条件

  • Python 3.12+

  • Spotify Premium 账户(自 2026 年 2 月起,开发模式 API 访问必需)

  • Spotify 开发者应用凭据

配置

1. 创建 Spotify 开发者应用

  1. 前往 developer.spotify.com/dashboard

  2. 创建一个新应用

  3. 将重定向 URI 设置为 http://127.0.0.1:8080/callback

  4. 记下你的 Client ID 和 Client Secret

重要 (2026 年 2 月):开发模式应用限制为 5 个授权用户,且要求应用所有者拥有 Spotify Premium。

2. 初始认证

运行一次认证流程以获取 OAuth 令牌:

SPOTIFY_CLIENT_ID=your_id SPOTIFY_CLIENT_SECRET=your_secret uv run spotify-mcp --auth

这将打开浏览器进行 Spotify 登录,然后将令牌保存到 ~/.spotify_mcp_cache.json。

3. 添加到 MCP 客户端

本地运行(推荐)

git clone https://github.com/verIdyia/spotify-mcp.git

添加到你的 MCP 配置(Claude Desktop、Cursor 等):

{
  "mcpServers": {
    "spotify": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/spotify-mcp",
        "run",
        "spotify-mcp"
      ],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret",
        "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8080/callback"
      }
    }
  }
}

使用 uvx 运行

{
  "mcpServers": {
    "spotify": {
      "command": "uvx",
      "args": [
        "--python", "3.12",
        "--from", "git+https://github.com/verIdyia/spotify-mcp",
        "spotify-mcp"
      ],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret",
        "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8080/callback"
      }
    }
  }
}

环境变量

变量

必需

默认值

描述

SPOTIFY_CLIENT_ID

是

--

Spotify 应用 Client ID

SPOTIFY_CLIENT_SECRET

是

--

Spotify 应用 Client Secret

SPOTIFY_REDIRECT_URI

否

http://127.0.0.1:8080/callback

OAuth 重定向 URI

SPOTIFY_CACHE_PATH

否

~/.spotify_mcp_cache.json

令牌缓存文件路径

故障排除

  1. 首次运行:在使用 MCP 客户端之前,请运行 spotify-mcp --auth 完成 OAuth 流程

  2. 令牌过期:令牌会自动刷新。如果问题仍然存在,请重新运行 --auth

  3. 无活动设备:确保 Spotify 已打开并在至少一台设备上播放

  4. 确保 uv 已更新 -- 建议版本 >=0.54

调试

启动 MCP Inspector:

npx @modelcontextprotocol/inspector uv --directory /path/to/spotify-mcp run spotify-mcp

Spotify API 2026 年 2 月变更摘要

变更

影响

状态

搜索 limit 最大值从 50 减至 10

每次搜索结果减少

已适配

播放列表端点 /tracks -> /items

端点 URL 变更

已适配

响应字段 tracks -> items

解析已更新

已适配

批量 GET 端点移除

必须单独获取

已适配

移除曲目的 popularity 字段

不再可用

已处理

开发模式:5 用户限制,需 Premium

访问限制

已记录

鸣谢

许可证

MIT 许可证 -- 详情请参阅 LICENSE。

Available Tools

6 tools
SpotifyGetInfoC

Get detailed information about a Spotify item...

Inputs: item_uri (required).

SpotifyLikedSongsC

Get user's liked (saved) songs from Spotify library.

Inputs: action (required), limit.

SpotifyPlaybackC

Manages the current playback...

Inputs: action (required), spotify_uri, num_skips.

SpotifyPlaylistC

Manage Spotify playlists.

Inputs: action (required), playlist_id, track_ids, name, +2 more.

SpotifyQueueC

Manage the playback queue - get the queue or add tracks.

Inputs: action (required), track_id.

SpotifySearchC

Search for tracks, albums, artists, or playlists on Spotify.

Inputs: query (required), qtype, limit.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose targeting different Spotify resources: GetInfo for item details, LikedSongs for saved songs, Playback for current playback control, Playlist for playlist management, Queue for queue operations, and Search for finding content. There is no overlap or ambiguity between these functions.

    Naming Consistency5/5

    All tools follow a consistent 'Spotify' prefix with descriptive noun-based naming (e.g., SpotifyGetInfo, SpotifyPlaylist). The pattern is uniform across all six tools, making them easily identifiable and predictable.

    Tool Count5/5

    With 6 tools, this server is well-scoped for Spotify integration, covering key areas like playback, playlists, search, and user library. Each tool serves a specific, necessary function without bloat or redundancy.

    Completeness4/5

    The toolset covers core Spotify functionalities including search, playback control, playlist management, and user data access. Minor gaps might include operations like following artists or managing user profile settings, but the provided tools support most common workflows effectively.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      F
      maintenance
      An MCP server that enables users to control Spotify playback, search for music, and manage playlists through MCP-compatible clients. It supports features like track recommendations and playback management using secure OAuth authentication.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      MCP server for the Spotify Web API — gives Claude and other AI assistants tools to search music, control playback, manage playlists, library, and podcasts.
      47
      5
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      An unofficial MCP server that provides access to Spotify's Web API through the Model Context Protocol, enabling AI assistants to search music, manage playlists, and control playback.
      9
      -
    • A
      license
      B
      quality
      D
      maintenance
      A Model Context Protocol server that enables searching and managing Spotify music, playlists, artists, albums, and audiobooks through natural language.
      24
      MIT