Spotify OAuth MCP Server

🚀 Spotify MCP 服務器

這是一個全面的模型上下文協議（MCP） 服務器，它能讓 AI 助手（如 Claude Desktop）與 Spotify Web API 實現無縫集成。該服務器使 AI 助手能夠通過一個結構良好、類型安全的接口與 Spotify 的音樂流媒體服務進行交互。

🚀 快速開始

1. 克隆並安裝

git clone <repository-url>
cd Spotify-OAuth-MCP-server
npm install

2. 獲取 Spotify 訪問令牌

3. 構建並啟動

# 構建 TypeScript 代碼
npm run build

# 啟動 MCP 服務器
npm start

# 開發模式，支持自動重新加載
npm run dev

✨ 主要特性

🛠️ 29 種綜合工具，涵蓋 7 個類別：

• 專輯（4 種工具）：專輯信息和新發行內容
• 藝術家（6 種工具）：藝術家數據、熱門曲目和發現功能
• 曲目（8 種工具）：曲目詳情、歌詞和庫管理
• 播放列表（10 種工具）：完整的播放列表管理和發現功能
• 播放（10 種工具）：全面的播放器控制和設備管理
• 用戶（1 種工具）：用戶個人資料信息
• 搜索（2 種工具）：通用搜索和搜索即播放功能

🏗️ 清晰的架構：

• 模塊化設計：基於功能的工具組織方式
• 類型安全：完全採用 TypeScript 實現，並使用 Zod 進行驗證
• 可複用組件：通用的模式構建器避免了代碼重複
• 自動註冊：工具會自動被發現並註冊
• 錯誤處理：全面的錯誤管理，提供詳細的錯誤信息

🔧 開發者體驗：

• 易於擴展：添加新工具的模式簡單
• 代碼可維護：關注點分離清晰
• 文檔完善：模式定義具有自文檔性
• 調試方便：詳細的日誌記錄和錯誤報告

📦 安裝指南

按照快速開始部分的步驟進行操作：

1. 克隆倉庫並安裝依賴。
2. 獲取 Spotify 訪問令牌。
3. 構建並啟動服務器。

💻 使用示例

基礎用法

將此 MCP 服務器與 Claude Desktop 集成後，你可以使用自然語言命令，例如：

"播放我的發現週報播放列表"
"搜索披頭士樂隊的歌曲"
"將這首歌添加到我的收藏"
"跳到下一首曲目"
"創建一個名為 '清晨氛圍' 的新播放列表"
"搜索帶有輕鬆音樂的播放列表"
"顯示我本月的熱門藝術家"
"當前正在播放什麼？"
"將這首歌添加到我的播放隊列"
"獲取我最近播放的曲目"
"顯示這首歌的歌詞"
"獲取純文本歌詞以進行分析"

🔧 Claude Desktop 集成

要在 Claude Desktop 中使用此 MCP 服務器，將其添加到你的 MCP 配置中：

macOS/Linux：~/Library/Application Support/Claude/claude_desktop_config.json

Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "spotify": {
      "command": "node",
      "args": ["/path/to/your/project/src/mcp/server.js"]
    }
  }
}

📚 詳細文檔

🏗️ 項目架構

src/
├── mcp/
│   ├── server.ts              # 主 MCP 服務器入口點
│   ├── helpers/
│   │   └── utils.ts          # 實用函數和輔助工具
│   ├── schemas/
│   │   └── common.ts         # 可複用的模式構建器
│   └── tools/
│       ├── index.ts          # 工具註冊表和註冊系統
│       ├── albums.ts         # 與專輯相關的工具（4 種工具）
│       ├── artists.ts        # 與藝術家相關的工具（6 種工具）
│       ├── tracks.ts         # 與曲目相關的工具（8 種工具）
│       ├── playlists.ts      # 播放列表管理工具（10 種工具）
│       ├── playback.ts       # 播放控制工具（10 種工具）
│       ├── user.ts           # 用戶個人資料工具（1 種工具）
│       └── search.ts         # 搜索功能工具（2 種工具）
└── spotify.ts                # Spotify Web API 服務類

架構優勢

1. 模塊化：每個工具類別都是獨立的
2. 類型安全：全程使用 TypeScript 和 Zod 進行驗證
3. 可複用性：通用模式避免了代碼重複
4. 可擴展性：易於添加新工具和類別
5. 可維護性：關注點分離清晰
6. 性能：高效的註冊和驗證機制

🛠️ 可用工具

專輯（4 種工具）

• get_album：獲取詳細的專輯信息
• get_album_tracks：獲取特定專輯中的曲目
• get_new_releases：發現新發行的專輯
• search_albums：按關鍵詞搜索專輯

藝術家（6 種工具）

• get_artist：獲取詳細的藝術家信息
• get_artist_albums：獲取藝術家的專輯
• get_artist_top_tracks：獲取藝術家最熱門的曲目
• search_artists：按關鍵詞搜索藝術家
• get_followed_artists：獲取用戶關注的藝術家
• get_top_artists：獲取用戶的熱門藝術家

曲目（8 種工具）

• get_track：獲取詳細的曲目信息
• search_tracks：按關鍵詞搜索曲目
• get_liked_tracks：獲取用戶收藏/喜歡的曲目
• save_tracks：將曲目添加到用戶的音樂庫
• remove_tracks：從用戶的音樂庫中移除曲目
• get_top_tracks：獲取用戶的熱門曲目
• get_recently_played：獲取最近播放的曲目
• get_track_lyrics：獲取曲目的純文本歌詞

播放列表（10 種工具）

• get_playlist：獲取播放列表詳情
• get_user_playlists：獲取用戶的播放列表
• get_playlist_tracks：獲取播放列表中的曲目
• create_playlist：創建新的播放列表
• add_to_playlist：將曲目添加到播放列表
• remove_from_playlist：從播放列表中移除曲目
• search_playlists：按關鍵詞搜索播放列表
• get_categories：獲取瀏覽類別
• save_playlist：關注/收藏用戶創建的播放列表
• unsave_playlist：取消關注/收藏播放列表

播放（10 種工具）

• get_currently_playing：獲取當前播放信息
• start_playback：開始音樂播放
• resume_player：恢復暫停的播放
• pause_player：暫停當前播放
• skip_to_next：跳到下一首曲目
• skip_to_previous：跳到上一首曲目
• set_volume：調整播放音量
• add_to_queue：將歌曲添加到播放隊列
• get_devices：獲取可用的播放設備
• transfer_playback：在設備之間切換播放

用戶（1 種工具）

• get_user_profile：獲取當前用戶的個人資料信息

搜索（2 種工具）

• search_music：搜索曲目、藝術家、專輯或播放列表
• search_and_play_music：搜索內容並立即開始播放

願你與 AI 一同享受愉快的音樂流媒體體驗！🎵🤖