AI导哈

播放列表相似性引擎

一个基于自然语言和多种相似性算法创建和管理Spotify播放列表的服务，支持音频特征分析和流派匹配。

  • by kylestratis
  • Python
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 kylestratis/spotify-mcp

使用说明

Spotify播放列表MCP服务器

一种模型上下文协议服务器，用于使用自然语言动态创建播放列表，包括对相似曲目使用几种相似方法之一。

这是为了缓解两种个人瘙痒：

  1. 使用自然语言和几个相似性指标之一构建播放列表。理想的是短暂的播放列表，但唉。
  2. 尝试新的Claude技能，看看它对人工智能辅助编码有多大帮助。结论：它可能会咀嚼代币，但效果很好。

**警告**：这仍然需要在现实世界的测试中进行测试，并为其编写一些评估。

特性

核心播放列表管理

  • 创建和管理Spotify播放列表
  • 在Spotify的目录中搜索曲目
  • 获取赛道详细信息和建议
  • 浏览用户播放列表和播放列表内容

高级相似性引擎

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

可用工具

基本工具

  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 -从特定播放列表中获取曲目

高级相似性工具

  1. spotify_get_audio_features -获取曲目的详细音频功能
  2. spotify_find_similar_tracks -高级相似性引擎（见下文）

相似性引擎

运作原理

相似性引擎使用两种方法找到相似的轨迹：

  1. 音频特征分析：分析声音特性，如能量、节奏和可跳舞性
  2. 类型匹配：比较艺术家流派的风格相似性

对于音频功能分析，该引擎使用Spotify的音频分析API来提取以下功能：

  • 声学 （0-1）：曲目使用声学乐器的信心
  • 舞蹈性 （0-1）：多么适合跳舞
  • 能量 （0-1）：强度和活动水平
  • 乐器 （0-1）：没有人声的可能性
  • 价 （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. Python 3.12+ （用mise管理）
  2. 紫外线 用于依赖关系管理
  3. Spotify开发者帐户 和API证书

设置

  1. 克隆存储库：
git clone <repository-url>
cd spotify-playlist-mcp
  1. 安装依赖项：
uv sync
  1. 配置环境变量：
cp .env.example .env
# Edit .env and add your SPOTIFY_ACCESS_TOKEN
  1. 获取您的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 Desktop安装

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. 特征标准化 -将音频功能标准化为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 （相似性策略）：要使用的算法
  • weights （可选[特征权重]）：自定义特征权重
  • scope （SearchScope）：在哪里搜索
  • scope_id （可选[str]）：作用域ID（播放列表/艺术家/专辑）
  • limit （int）：结果数（1-100）
  • min_similarity （可选[float]）：最小相似性阈值
  • action （相似性行动）：如何处理结果
  • playlist_name （可选[str]）：新播放列表的名称
  • target_playlist_id （可选[str]）：添加曲目的目标
  • 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波段匹配
  • 密钥和模式兼容性检查
  • 音频分析集成（小节、节拍、片段）
  • 高级流派层次结构和分类
  • 多艺术家协作检测

致谢

支持

对于问题、疑问或功能请求，请在GitHub上打开问题。

相关 MCP