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。