Spotify MCP

🚀 Spotify播放列表MCP服务器

这是一个模型上下文协议（MCP）服务器，可让你使用自然语言即时创建播放列表，还能通过多种相似性方法来查找相似曲目。它主要解决了以下两个个人需求：

1. 借助自然语言和多种相似性指标创建播放列表，理想情况下能创建临时播放列表。
2. 体验Claude的新技能，看看它在人工智能辅助编码方面的效果。结论是：虽然会消耗一定的令牌，但效果非常好。

警告：该项目仍需在实际场景中进行全面测试，并编写相关评估。

✨ 主要特性

核心播放列表管理

• 创建和管理Spotify播放列表
• 在Spotify曲库中搜索曲目
• 获取曲目详情和推荐
• 浏览用户播放列表及其内容

高级相似性引擎

• 音频特征分析：提取并分析声学性、可舞性、能量、节奏、情绪等特征。
• 多种相似性算法：提供8种不同策略供你选择（欧几里得、余弦、加权、曼哈顿、能量匹配、情绪匹配、节奏匹配、流派匹配）。
• 基于流派的匹配：在播放列表或收藏中查找具有相似艺术家流派的曲目。
• 可定制的特征权重：通过对特定音频特征加权，微调相似性计算。
• 灵活的搜索范围：可在整个曲库、播放列表、艺术家唱片集、专辑或已保存曲目中进行搜索。
• 自动化操作：查找相似曲目，并自动创建播放列表或添加到现有列表中。

📦 安装指南

前提条件

1. Python 3.12+（使用mise管理）
2. uv 用于依赖管理
3. Spotify开发者账户 及API凭证

安装步骤

1. 克隆仓库：

git clone <repository-url>
cd spotify-playlist-mcp

2. 安装依赖：

uv sync

3. 配置环境变量：

cp .env.example .env
# 编辑.env文件并添加你的SPOTIFY_ACCESS_TOKEN

4. 获取Spotify访问令牌（详细说明见 .env.example）：
   • 访问 Spotify开发者控制台
   • 创建一个应用
   • 获取客户端ID和客户端密钥
   • 生成具有以下所需权限的访问令牌：
     • playlist-modify-public
     • playlist-modify-private
     • playlist-read-private
     • user-read-private

💻 使用示例

运行服务器

开发模式（使用MCP检查器）

uv run mcp dev server.py

直接执行

uv run python server.py

为Claude桌面版安装

uv run mcp install server.py

示例用例

在播放列表中查找相似曲目

"Find songs similar to track [ID] within my workout playlist"

根据曲目创建播放列表

"Find tracks similar to [track name] using the energy_match strategy
and create a playlist called 'High Energy Workout'"

自定义加权相似性

"Find tracks similar to this song, but prioritize energy and danceability
more than other features (weights: energy=5.0, danceability=5.0)"

根据艺术家风格创建情绪播放列表

"Create a calm acoustic playlist based on [artist name]'s style
using the mood_match strategy"

搜索已保存曲目

"Find all tracks in my saved library that sound similar to this song"

基于流派的播放列表过滤

"Create a playlist with tracks from my Discover Weekly that have
the same genre as this track I'm listening to"

相似性引擎示例

示例1：在播放列表中查找相似曲目

{
  "track_id": "3n3Ppam7vgaVa1iaRUc9Lp",
  "strategy": "euclidean",
  "scope": "playlist",
  "scope_id": "37i9dQZF1DXcBWIGoYBM5M",
  "limit": 10,
  "action": "return_tracks"
}

示例2：创建高能量健身播放列表

{
  "track_id": "4iV5W9uYEdYUVa79Axb7Rh",
  "strategy": "energy_match",
  "scope": "catalog",
  "limit": 30,
  "action": "create_playlist",
  "playlist_name": "High Energy Workout"
}

示例3：自定义加权相似性

{
  "track_id": "7qiZfU4dY1lWllzX7mPBI",
  "strategy": "weighted",
  "weights": {
    "energy": 5.0,
    "danceability": 5.0,
    "valence": 3.0,
    "acousticness": 0.5,
    "tempo": 2.0
  },
  "scope": "catalog",
  "limit": 20,
  "action": "create_playlist",
  "playlist_name": "Custom Mix"
}

示例4：根据艺术家风格查找相似曲目

{
  "artist_id": "0OdUWJ0sBjDrqHygGUXeCF",
  "strategy": "cosine",
  "scope": "saved_tracks",
  "limit": 15,
  "action": "add_to_playlist",
  "target_playlist_id": "5FqPqTauQoRPRxJBQC8C2N"
}

示例5：基于流派的播放列表过滤

查找与特定曲目流派匹配的播放列表中的曲目：

{
  "track_id": "3n3Ppam7vgaVa1iaRUc9Lp",
  "strategy": "genre_match",
  "scope": "playlist",
  "scope_id": "37i9dQZF1DXcBWIGoYBM5M",
  "limit": 20,
  "action": "create_playlist",
  "playlist_name": "Same Genre from Discover Weekly"
}

注意：genre_match 策略需要指定特定范围（播放列表、艺术家、专辑或已保存曲目），不能用于整个曲库范围。

📚 详细文档

可用工具

基础工具

1. spotify_search_tracks - 按名称、艺术家或查询词搜索曲目
2. spotify_get_track - 获取特定曲目的详细信息
3. spotify_get_recommendations - 获取可调整参数的曲目推荐
4. spotify_create_playlist - 创建新的Spotify播放列表
5. spotify_add_tracks_to_playlist - 将曲目添加到现有播放列表
6. spotify_get_user_playlists - 分页列出用户的播放列表
7. spotify_get_playlist_tracks - 获取特定播放列表中的曲目

高级相似性工具

8. spotify_get_audio_features - 获取曲目的详细音频特征
9. spotify_find_similar_tracks - 高级相似性引擎（详见下文）

相似性引擎

工作原理

相似性引擎通过两种方法查找相似曲目：

1. 音频特征分析：分析能量、节奏、可舞性等声学特征。
2. 流派匹配：比较艺术家流派以实现基于风格的匹配。

对于音频特征分析，引擎使用Spotify的音频分析API提取以下特征：

• 声学性 (0 - 1)：曲目使用原声乐器的置信度
• 可舞性 (0 - 1)：适合跳舞的程度
• 能量 (0 - 1)：强度和活跃度
• 乐器性 (0 - 1)：无 vocals 的可能性
• 情绪 (0 - 1)：音乐的积极程度（快乐/欢快）
• 节奏 (BPM)：曲目的速度
• 响度 (dB)：整体音量
• 口语性 (0 - 1)：口语的存在程度
• 现场感 (0 - 1)：观众的存在（现场表演）

相似性策略

提供8种不同的算法供你选择：

1. euclidean（默认） - 使用欧几里得距离计算所有特征的总体相似性
2. weighted - 自定义加权相似性 - 指定每个特征的重要性
3. cosine - 角度相似性（适用于高维匹配）
4. manhattan - 曼哈顿距离度量
5. energy_match - 专注于能量和可舞性，适用于健身/派对播放列表
6. mood_match - 专注于情绪和声学性，适用于情绪匹配的播放列表
7. rhythm_match - 专注于节奏，适用于基于节奏的相似性匹配
8. genre_match - 根据艺术家流派匹配曲目（精确和部分匹配）

搜索范围

控制在何处搜索相似曲目：

• catalog - 搜索整个Spotify曲库（使用推荐API）
• playlist - 在特定播放列表中查找相似曲目
• artist - 在艺术家的唱片集中搜索
• album - 在特定专辑中查找相似曲目
• saved_tracks - 在用户的已保存曲库中搜索

操作

选择对相似曲目执行的操作：

• return_tracks - 仅返回带有相似性分数的曲目列表
• create_playlist - 自动创建包含相似曲目的新播放列表
• add_to_playlist - 将相似曲目添加到现有播放列表

架构

模块化设计

相似性引擎采用模块化设计：

1. 特征归一化 - 将音频特征归一化为0 - 1范围
2. 相似性计算器 - 可插拔的距离/相似性函数
3. 范围处理程序 - 从不同来源提取候选曲目
4. 操作执行器 - 处理不同的输出操作

添加自定义策略

要添加新的相似性策略：

1. 将策略添加到 SimilarityStrategy 枚举中
2. 在 _calculate_similarity() 中实现计算逻辑
3. 在工具描述中记录该策略

API参考

spotify_find_similar_tracks

参数：

• track_id (可选[str])：源曲目ID
• artist_id (可选[str])：源艺术家ID
• playlist_id (可选[str])：源播放列表ID
• strategy (SimilarityStrategy)：要使用的算法
• weights (可选[FeatureWeights])：自定义特征权重
• scope (SearchScope)：搜索范围
• scope_id (可选[str])：范围的ID（播放列表/艺术家/专辑）
• limit (int)：结果数量（1 - 100）
• min_similarity (可选[float])：最小相似性阈值
• action (SimilarityAction)：对结果执行的操作
• playlist_name (可选[str])：新播放列表的名称
• target_playlist_id (可选[str])：添加曲目的目标播放列表ID
• response_format (ResponseFormat)：'markdown' 或 'json'

返回值：

• 带有相似性分数的相似曲目列表
• 或播放列表创建确认信息
• 或添加到播放列表的确认信息

🔧 技术细节

模块化设计优势

相似性引擎的模块化设计使得系统具有良好的可扩展性和维护性。特征归一化模块确保了不同音频特征在计算相似性时具有可比性；相似性计算器模块可以方便地添加新的相似性算法；范围处理程序模块能够灵活地从不同数据源提取候选曲目；操作执行器模块则负责将相似性计算结果转化为具体的操作，如创建播放列表或添加曲目。

相似性算法实现

不同的相似性算法在计算相似性时采用了不同的数学方法。例如，欧几里得距离算法通过计算特征向量之间的欧几里得距离来衡量相似性；余弦相似度算法则通过计算特征向量之间的夹角来衡量相似性。这些算法的选择取决于具体的应用场景和用户需求。

📄 许可证

文档中未提及相关许可证信息。

🛠️ 故障排除

音频特征已弃用错误

如果你遇到音频特征已弃用的错误：

• 确保你的Spotify应用具有扩展模式访问权限。
• 注意：自2024年11月起，新应用的音频特征端点已被弃用，但具有扩展模式访问权限的现有应用仍可使用。

身份验证错误

• 访问令牌有效期为1小时，请定期刷新。
• 确保已授予所有必需的权限。
• 检查 .env 文件中是否正确设置了令牌。

速率限制

• Spotify API 有速率限制，服务器会优雅地处理429错误。
• 如果搜索大型播放列表，请耐心等待，因为可能需要一些时间。

💡 使用建议

1. 令牌管理：在生产环境中实现令牌刷新逻辑。
2. 范围选择：使用特定范围（播放列表/艺术家/专辑）以提高性能。
3. 策略选择：
   • 一般相似性使用 euclidean。
   • 健身/派对播放列表使用 energy_match。
   • 放松/学习播放列表使用 mood_match。
   • 基于节奏的匹配（跑步、跳舞）使用 rhythm_match。
   • 按流派过滤播放列表使用 genre_match。
   • 当你知道哪些特征最重要时使用 weighted。
4. 流派匹配注意事项：
   • 需要特定范围（播放列表、艺术家、专辑或已保存曲目）。
   • 不适用于整个曲库范围。
   • 最适合按流派过滤现有收藏。
   • 使用艺术家流派（没有艺术家流派数据的曲目将被跳过）。
5. 批量操作：分析多个曲目时，使用批量端点。
6. 错误处理：在继续操作之前，始终检查响应是否有错误。

🤝 贡献

欢迎贡献代码！以下是可以改进的方向：

• 增加更多相似性策略
• 实现更复杂的特征加权算法
• 支持节奏范围匹配和BPM频段
• 检查调式和模式兼容性
• 集成音频分析（小节、节拍、片段）
• 构建高级流派层次结构和分类法
• 检测多艺术家合作

🙏 致谢

• 基于 FastMCP 构建，该项目出现在 MCP Python SDK 中。
• 使用 Spotify Web API。
• 遵循 Model Context Protocol 规范。
• 使用 mcp-builder Claude 技能改进代码生成。

🆘 支持

如果你遇到问题、有疑问或有功能请求，请在GitHub上创建一个issue。