使用说明

Spotify MCP服务器

为Claude Desktop提供Spotify集成的模型上下文协议（MCP）服务器。

⚠️ 这个项目是实验性的/仅供个人使用

这个存储库是一个为娱乐和学习而创建的个人项目。它还没有经过彻底的测试或生产硬化。使用风险由您自行承担，包括在范围发生变化时重新进行身份验证，以及备份任何重要数据。

特性

🔍 搜索

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

🎵 播放控制

获取当前播放状态
播放/暂停、跳过、上一首曲目
控制音量和洗牌
在轨道内寻找

📚 图书馆管理

获取已保存的曲目
保存和删除库中的曲目
检查曲目是否已保存

🎼 播放列表

获取用户播放列表
创建新播放列表
在播放列表中添加/删除曲目
获取播放列表详细信息

🎯 建议

根据以下内容获得个性化推荐：
- 种子曲目、艺术家或流派
- 情绪偏好（能量、跳舞能力、价格）
- 根据最近的收听历史自动推荐
获取可用的流派种子

💬 智能提示

发现音乐：根据心情和偏好获取建议
分析当前播放：对当前播放曲目的深入分析
创建主题播放列表：围绕主题或活动构建播放列表

设置

1.创建Spotify应用程序

首选 Spotify开发者仪表板
点击“创建应用”
填写：
- 应用程序名称：“MCP Spotify”（或任何名称）
- 应用程序描述：“个人Spotify MCP服务器”
- 重定向URI: http://localhost:3000/callback
查看“您计划使用哪些API/SDK？”下的“Web API”
同意条款并点击“保存”
点击“设置”查看您的 客户端ID 和 客户端密钥

2.配置环境

创建一个 .env 项目根目录中的文件：

SPOTIFY_CLIENT_ID=your_client_id_here
SPOTIFY_CLIENT_SECRET=your_client_secret_here
SPOTIFY_REDIRECT_URI=http://localhost:3000/callback

3.构建服务器

npm install
npm run build

4.配置克劳德桌面

编辑您的Claude Desktop配置文件：

窗户： %APPDATA%\Claude\claude_desktop_config.json
macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

添加MCP服务器配置：

{
  "mcpServers": {
    "mcp-spotify": {
      "command": "node",
      "args": [
        "C:\\path\\to\\mcp-spotify\\build\\index.js"
      ]
    }
  }
}

替换 C:\\path\\to\\mcp-spotify 与这个项目的实际路径。

5.首次运行身份验证

重新启动克劳德桌面
服务器将自动打开浏览器进行Spotify身份验证
登录并授权应用程序
您将被重定向到成功页面
令牌保存到 ~/.mcp-spotify/tokens.json

可用工具

搜索

search_tracks -搜索曲目
search_albums -搜索相册
search_artists -寻找艺术家
search_playlists -搜索播放列表

回放

get_playback_state -获取当前播放信息
playback_control -控制播放（播放、暂停、跳过、上一步、混洗、音量、寻道）

图书馆

get_saved_tracks -获取用户保存的曲目
save_tracks -将曲目保存到库
remove_saved_tracks -从库中删除曲目
get_recently_played -获取最近播放的曲目（可用于推荐）

播放列表

get_playlists -获取用户的播放列表
create_playlist -创建新的播放列表
add_tracks_to_playlist -将曲目添加到播放列表

建议

get_recommendations -根据种子和偏好获取跟踪建议（支持 use_recent_listening 参数）
get_genre_seeds -获取可用流派种子列表

可用提示

`discover_music`

根据您的心情、流派和收听偏好发现新音乐。

论据：

mood （可选）：期望的情绪（精力充沛、冷静、快乐、忧郁）
genre （可选）：首选流派

例子： “发现充满活力的电子音乐”

`analyze_now_playing`

获取当前播放曲目的详细分析，包括音频功能和建议。

例子： “分析我在听什么”

`create_themed_playlist`

根据主题、情绪或活动创建播放列表。

论据：

theme：主题或情绪（例如，“锻炼”、“学习”、“公路旅行”）
size （可选）：轨道数量（默认值：20）

例子： “创建一个包含30首歌曲的寒意学习播放列表”

交互示例

You: "What am I currently listening to?"
→ Uses get_playback_state to show current track

You: "Find me some energetic electronic music"
→ Uses search_tracks or get_recommendations with appropriate filters

You: "Create a workout playlist"
→ Uses create_themed_playlist prompt to search, gather tracks, and create playlist

You: "Save this track to my library"
→ Uses save_tracks to add the current or mentioned track

You: "Skip to the next song"
→ Uses playback_control with action: "skip"

项目结构

src/
  ├── index.ts                 # Main entry point, server setup
  ├── auth.ts                  # OAuth 2.0 authentication flow
  ├── spotify-client.ts        # HTTP client for Spotify API
  ├── logger.ts                # Logging utility
  ├── types.ts                 # TypeScript type definitions
  ├── utils.ts                 # Helper utilities
  ├── tools/
  │   ├── search.ts            # Search functionality
  │   ├── playback.ts          # Playback control
  │   ├── library.ts           # Library management
  │   ├── playlists.ts         # Playlist operations
  │   ├── recommendations.ts   # Recommendations logic
  │   └── declarations/
  │       └── *.ts             # Tool registration
  └── prompts/
      └── declarations/
          └── *.ts             # Prompt registration

故障排除

“Spotify API错误：401”

令牌可能已过期。删除 ~/.mcp-spotify/tokens.json 并重新启动克劳德
检查您的客户端ID和客户端密码是否正确 .env

“未找到播放设备”

在任何设备（台式机、移动设备、网络）上打开Spotify
开始播放任何曲目以激活设备
API需要一个用于播放控制的活动设备

建议返回404

这是意料之中的！Spotify反对旧的建议API
服务器现在使用带有过滤器的搜索API作为替换

技术细节

语言： TypeScript
运行时间： Node.js v23.9.0
MCP-SDK： @modelcontextprotocol/sdk v1.20.0
运输： 标准
认证： 带有刷新令牌的OAuth 2.0授权代码流
令牌存储： ~/.mcp-spotify/tokens.json （自动刷新）

许可证

麻省理工学院