Spotify MCP Enhanced Music Overload

Spotify mcp过载

一种模型上下文协议（MCP）服务器，使Claude Code CLI或Desktop能够与Spotify交互，以进行播放列表管理和管理等。

Rock Out具有以下功能：

• 🧠 智能播放列表管理
• 🛤️ 深度轨迹识别
• 🕺 歌曲分析（bpm、舞蹈性等）
• 🚀 发现和推荐（带种子验证）

特性

🚦核心播放列表管理

• 创建播放列表
• 搜索曲目
• 将曲目添加到播放列表（具有自动速率限制处理功能）
• 从播放列表中删除曲目（使用自动速率限制处理）
• 获取用户播放列表
• 获取播放列表曲目

🧠 智能策划与发现

• 获取您的热门曲目 -查看你最常听的内容（按时间段）
• 获取跟踪建议（通过种子验证）
• 创建精心策划的播放列表 -基于您的热门曲目+推荐的自动播放列表
• 在播放列表中查找重复曲目

📈 音频分析

• 获取音频功能 -BPM、音乐键、能量、舞蹈性、效价、声学
• 多源数据 -GetSongBPM API+MusicBrainz/AcousticBrainz瀑布
• 智能缓存 -30天TTL，正/负缓存，以减少API调用
• 无需预览 -适用于ISRC查找，不依赖于30秒的预览
• 覆盖：流行/老曲目约70-90%，最新版本（2020+）约20-40%

🛠️ 可靠性特征

• Spotify API速率限制上的自动重试（HTTP 429）
• 批量处理大型操作（100+轨道）
• 异步执行-音频分析在线程池中运行（无阻塞）

先决条件

• Python 3.10或更高版本
• Spotify帐户
• Spotify开发者应用程序（用于API证书）

设置

1.获取Spotify API证书

1. 首选 Spotify开发者仪表板
2. 点击“创建应用”
3. 填写：

- 应用程序名称：“spotify mcp增强音乐过载” - 应用程序描述：“用于Claude集成的MCP服务器” - 重定向URI: http://127.0.0.1:8888/callback - 使用的API：检查“Web API”

1. 接受条款并单击“保存”
2. 点击“设置”查看您的 客户端ID 和 客户端密钥

2.安装依赖项

cd spotify-mcp
pip install -e .

这将安装所有必需的依赖项，包括音频功能支持。

3.获取免费GetSongBPM API密钥（可选但推荐）

要增强音频功能覆盖范围：

1. 首选 GetSongBPM API
2. 注册免费API密钥

4.配置环境

# Copy the example env file
cp .env.example .env

# Edit .env and add your credentials:
# SPOTIFY_CLIENT_ID=your_actual_client_id
# SPOTIFY_CLIENT_SECRET=your_actual_client_secret
# GETSONGBPM_API_KEY=your_api_key (optional but recommended)

5.首次运行身份验证

第一次运行服务器时，它将：

1. 自动打开浏览器
2. 请您授权该应用程序
3. 重定向至 http://127.0.0.1:8888/callback
4. 将身份验证令牌保存在本地 .spotify_cache

备注：重定向URL将在您的浏览器中显示错误（这是正常的）。身份验证令牌会自动从URL中提取。

第一次运行后，令牌将被缓存，除非过期，否则您不需要再次进行身份验证。

用法

使用克劳德桌面

添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "spotify": {
      "command": "/opt/miniconda3/bin/python",
      "args": ["/absolute/path/to/spotify-mcp/src/server.py"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret",
        "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8888/callback",
        "SPOTIFY_CACHE_PATH": "/absolute/path/to/.spotify_cache"
      }
    }
  }
}

重要:

• 使用 Python的绝对路径 （例如。， /opt/miniconda3/bin/python 或 /usr/bin/python3)-找到它 which python
• 对所有文件路径使用绝对路径，而不是相对路径
• 替换 /absolute/path/to/spotify-mcp 与你的实际路径
• 替换 your_client_id 和 your_client_secret 使用您的真实凭证

添加配置后重新启动Claude Desktop。

小贴士：参见 TESTING_GUIDE.md 了解全面的Claude Desktop设置说明。

使用Claude Code CLI

推荐用于大型播放列表和复杂的工作流程！ Claude Code CLI的上下文窗口比Claude Desktop大得多，非常适合：

• 创建包含100多首曲目的播放列表
• 多步骤管理工作流程
• 跨多个播放列表的批处理操作

添加到您的设置文件中：

位置: ~/.claude/settings.json

{
  "mcpServers": {
    "spotify": {
      "description": "Spotify playlist curation and management. 10 tools for smart playlist creation.",
      "command": "/opt/miniconda3/bin/python",
      "args": ["/absolute/path/to/spotify-mcp/src/server.py"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret",
        "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8888/callback",
        "SPOTIFY_CACHE_PATH": "/absolute/path/to/.spotify_cache"
      },
      "enabled": true
    }
  }
}

重要:

• 使用 Python的绝对路径 -找到它 which python
• 对所有文件路径使用绝对路径
• 添加配置后重新启动Claude Code CLI
• 看 CLAUDE_CODE_CLI_SETUP.md 有关详细的设置指南

与克劳德的对话示例

配置后，您可以向Claude询问以下问题：

创建播放列表

You: Create a workout playlist called "Morning Energy" with an upbeat description

Claude: [Uses create_playlist tool]
✅ Created playlist: Morning Energy
URL: https://open.spotify.com/playlist/abc123

搜索和添加曲目

You: Find some high-energy electronic music and add the top 5 tracks to my Morning Energy playlist

Claude: [Uses search_tracks and add_tracks_to_playlist tools]
Found 20 tracks. Adding top 5 to your playlist...
✅ Added 5 tracks to playlist

获取推荐

You: Based on my current "Psychedelic" playlist, recommend 10 similar songs

Claude: [Uses get_playlist_tracks and get_recommendations tools]
Here are 10 recommendations based on your playlist...

列出您的播放列表

You: Show me all my playlists

Claude: [Uses get_user_playlists tool]
Found 15 playlists:
1. Psychedelic (Public) - 25 tracks
2. Dub Reggae (Private) - 40 tracks
...

删除曲目

You: Remove all tracks by "Black Sabbath" from my workout playlist

Claude: [Uses get_playlist_tracks and remove_tracks_from_playlist tools]
Found 3 tracks by Black Sabbath. Removing...
✅ Removed 3 tracks from playlist

查找重复项

You: Find duplicate songs in my "Favorites" playlist

Claude: [Uses find_duplicates tool]
Found 5 duplicate tracks:
1. "I Was On A Mountain" by Hot Water Music - 2 occurrences
2. "Suffer" by Bad Religion - 2 occurrences
...

获取您的热门曲目

You: Show me my top 20 most-played tracks from the last 6 months

Claude: [Uses get_top_tracks tool]
Your top 20 tracks (last 6 months):
1. Saboteurs by Dave Hause
2. Web in Front by Archers Of Loaf
3. Cabin Fever by Slomosa
...

创建精心策划的播放列表

You: Create a personalized playlist based on my top tracks from the last month, including similar recommendations

Claude: [Uses create_curated_playlist_from_top_tracks tool]
✅ Created curated playlist: Personalized Mix

📊 Summary:
   - Total tracks added: 50
   - Your top tracks: 20
   - Recommendations: 30

🔗 Playlist URL: https://open.spotify.com/playlist/abc123

获取音频功能🎵

You: Analyze the audio features for Hot Water Music's "I Was On A Mountain"

Claude: [Uses search_tracks and get_audio_features tools]
🎵 Audio Features (The Mighty Mighty Bosstones - I Hope I Never Lose My Wallet)

🎼 Musical Properties:
   - Tempo: 102.0 BPM
   - Key: A minor
   - Time Signature: 4/4

📊 Energy & Mood:
   - Danceability: 0.440 (moderate)
   - Acousticness: 0.010 (very electric)

ℹ️  Data Source: GetSongBPM API

用例:

• 为DJ混音和锻炼播放列表查找具有类似BPM的曲目
• 检测和声混音的音乐键（DJ）
• 按能量/跳舞能力过滤主题播放列表中的曲目
• 分析情绪（效价）和声学以进行策划
• 构建具有一致节奏/能量流的集合列表

可用工具

总计：18个可用工具

可靠性特征

自动速率限制处理

服务器自动处理Spotify API速率限制（HTTP 429）：

• 阅读 Retry-After 来自Spotify的标题
• 等待指定时间
• 重试操作一次
• 将速率限制事件记录到stderr

这使得批量操作（添加/删除100多个轨道）可靠且有弹性。

批处理

自动批量请求修改播放列表的操作：

• 每次API呼叫最多100首曲目（Spotify限制）
• 处理任何大小的播放列表
• 保持批次内的操作原子性

输入验证

• get_recommendations 在进行API调用之前验证是否至少提供了一个种子
• 防止不必要的API请求带有明确的错误消息

故障排除

“身份验证失败”错误

• 验证您的客户端ID和客户端密码是否正确
• 确保Spotify应用程序设置中的重定向URI完全匹配： http://127.0.0.1:8888/callback
• 删除 .spotify_cache 并尝试再次进行身份验证

“没有名为'mcp'的模块”错误

• 跑 pip install -e . 从项目目录
• 确保你使用的是Python 3.10+

Claude Desktop中出现“spawn python ENOENT”错误

• 使用 完整路径 到配置中的Python解释器
• 通过以下方式查找： which python 或 which python3
• 例子： "command": "/opt/miniconda3/bin/python" 而不是 "command": "python"

Claude Desktop不显示Spotify工具

• 验证JSON配置语法是否正确
• 检查所有路径是否都是绝对的（不是相对的）
• 使用完整的Python路径（请参阅上面的“spawn Python ENOENT”）
• 配置更改后重新启动Claude Desktop
• 检查Claude Desktop日志是否有错误

浏览器未打开进行身份验证

• 第一次运行需要浏览器。手动运行服务器一次：

  cd spotify-mcp/src
  python server.py

• 身份验证成功后，将为Claude Desktop/CLI缓存令牌

“无可用音频功能”消息

• 赛道可能太近了（2020年后的覆盖率约为20-40%）
• 较旧/经典曲目的覆盖率更好（~70-90%）
• GetSongBPM API密钥显著提高了覆盖率
• MusicBrainz/AcousticBrainz于2022年停止收集数据
• 查找后，功能将缓存30天

安全说明

• 永不承诺 你的 .env 文件或 .spotify_cache 文件到版本控制
• 这 .spotify_cache 文件包含您的访问和刷新令牌
• 客户端机密应保密
• 此服务器专为您本地计算机上的个人使用而设计

发展

运行测试

pip install -e ".[dev]"
pytest

项目结构

spotify-mcp/
├── src/
│   ├── features/                  # Audio features module (Phase 2)
│   │   ├── __init__.py
│   │   ├── models.py             # Pydantic data models
│   │   ├── cache.py              # File-based caching (30-day TTL)
│   │   ├── service.py            # Multi-source orchestration
│   │   └── clients/              # API clients
│   │       ├── getsongbpm.py     # GetSongBPM API client
│   │       ├── musicbrainz.py    # MusicBrainz ISRC lookup
│   │       └── acousticbrainz.py # AcousticBrainz features
│   ├── clients/
│   │   └── spotify_client.py      # Spotify API wrapper
│   ├── logic/
│   │   ├── playlist_logic.py      # Playlist intelligence
│   │   └── artist_logic.py        # Artist deep dive
│   └── server.py                  # Main MCP server
├── pyproject.toml                 # Dependencies
├── .env.example                   # Example environment variables
└── README.md

鸣谢

访问来源https://getsongbpm.com/通过他们的免费API提供歌曲分析，包括beats-per-minute。谢谢，GetSongBPM.com

许可证

MIT许可证-随意修改和分发。让它变得更好。让它更凉爽。

贡献

问题和拉取请求欢迎！此实现包括核心功能，可以扩展为：

• 更多Spotify API端点
• 高级播放列表管理算法
• 用户库管理
• 协同过滤
• 曲目列表生成器（DJ曲目、音乐会曲目列表）
• 其他音频分析源

鸣谢

这个项目建立在优秀的开源工具和API之上：

核心依赖关系

• MCP（模型上下文协议） -Anthropic的LLM集成协议
• Spotipy 的 -Spotify Web API的Python库
• 派丹蒂克 -使用Python类型注释进行数据验证

音频功能数据源

• GetSongBPM API -节奏、音调和音频特征的主要来源-mucho gracias
• MusicBrainz -ISRC查找的开放音乐百科全书-杀手级
• AcousticBrainz -众包声学分析数据库（2022年存档）-非常酷

开发工具

• httpx -现代异步HTTP客户端
• 坚韧 -使用指数回退重试逻辑
• python dotenv -环境变量管理

](https://smithery.ai/server/@Beerspitnight/spotify-overload)

资源

• MCP文件
• Spotify Web API文档
• Spotipy图书馆
• GetSongBPM API文档
• MusicBrainz API