MCP Claude Spotify 是一个让 Claude Desktop 通过 Model Context Protocol（MCP）与 Spotify 进行交互的集成工具，由 imprvhub 开发并开源在 GitHub。
用途
该工具旨在将 Spotify 的音乐服务能力接入 Claude Desktop，使用户能够通过自然语言指令完成音乐搜索、播放控制、播放列表管理和收听历史查询等操作。它适合希望在 Claude 中直接操作 Spotify 的用户，例如整理播放列表、查找特定曲目或查看个人收听习惯。
主要能力
- Spotify 认证：支持通过 OAuth 流程授权 Spotify 账户，令牌会保存到用户目录下的
~/.spotify-mcp/tokens.json以实现持久化。 - 搜索功能：可搜索曲目、专辑、艺人和播放列表，支持指定返回数量。
- 播放控制：获取当前播放状态，播放指定曲目（可指定设备），暂停、切歌（下一首/上一首）。
- 播放列表管理：获取用户播放列表列表，创建新播放列表，更新名称、描述、公开/私有状态和协作设置，取消关注（移除）播放列表，分页获取播放列表内的曲目，添加或移除曲目，重新排序曲目，获取和上传自定义封面图（需 base64 编码的 JPEG，最大 256KB）。
- 发现与历史：获取用户在不同时间范围（约最近4周、6个月或数年）内最常播放的曲目，以及最近播放的曲目记录。
使用方式
使用前需具备：Node.js 20 或更高版本、Spotify 账户、Spotify API 凭据（Client ID 和 Client Secret）。可通过 Smithery 自动安装到 Claude Desktop，或手动克隆仓库、安装依赖并构建项目。需在 Spotify Developer Dashboard 创建应用，将重定向 URI 设置为 http://127.0.0.1:8888/callback，获取 Client ID 和 Client Secret。之后编辑 Claude Desktop 配置文件（macOS 为 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 为 %APPDATA%\Claude\claude_desktop_config.json），添加 spotify 配置节并填入绝对路径和凭据。首次认证可在终端运行服务器并设置 SPOTIFY_AUTO_AUTH=true 完成浏览器授权，或在 Claude 中使用 auth-spotify 命令。认证成功后需重启 Claude Desktop。
适用场景
- 通过 Claude 快速搜索并播放音乐。
- 整理和编辑 Spotify 播放列表（添加、删除、排序、修改信息）。
- 查询个人收听历史和热门曲目。
- 在 Claude 中统一管理 Spotify 操作，无需切换应用。
限制与注意事项
- 0.6.0 版本已移除
get-recommendations工具，因为 Spotify 于 2024 年 11 月 27 日弃用了/v1/recommendations及相关接口（related-artists、audio-features、audio-analysis、featured-playlists 和 30 秒预览 URL），在此日期后创建的应用会返回 403 Forbidden，开发模式下的应用也失去访问权限。建议改用search-spotify和get-top-tracks。 - 认证流程现已 CSRF 保护，登录 URL 携带随机 state 值；令牌文件以 600 权限存储于 700 目录中；回调仅监听 127.0.0.1；端口 8888 被占用时服务器会报告并停止，不会强制终止其他进程。
- 工具参数中的 ID 会进行验证，仅接受纯 Spotify ID。
- 常见问题包括“Server disconnected”错误、浏览器未自动打开、认证错误、服务器启动错误和工具未出现在 Claude 中，需检查配置、端口和 Node.js 版本等。
- 切勿分享 Client ID 和 Client Secret。
- 项目包含基于 Jest 的自动化测试，覆盖 Zod 模式验证、Spotify API 交互和 MCP 服务器功能。
