Spotify MCP Server

一个全面的**模型上下文协议（MCP）**服务器，提供AI助手（如Claude Desktop）与Spotify Web API之间的无缝集成。此服务器使AI助手能够通过结构良好、类型安全的接口与Spotify的音乐流服务进行交互。

🎵 概述

此MCP服务器作为AI助手与Spotify Web API之间的桥梁，允许用户：

• 搜索音乐、艺术家、专辑和播放列表
• 控制播放（播放、暂停、跳过、音量控制）
• 管理播放列表（创建、修改、添加/移除曲目）
• 访问用户资料和音乐库
• 管理用户的音乐库（保存/移除曲目）
• 获取用户的听歌历史和热门内容
• 获取纯文本歌词

✨ 主要特性

🛠️ 29个全面工具，分为7类：

• 专辑（4个工具）：专辑信息和新发布
• 艺术家（6个工具）：艺术家数据、热门曲目和发现
• 曲目（8个工具）：曲目详情、歌词和库管理
• 播放列表（10个工具）：完整的播放列表管理和发现
• 播放（10个工具）：完整的播放器控制和设备管理
• 用户（1个工具）：用户资料信息
• 搜索（2个工具）：通用搜索和搜索到播放功能

🏗️ 清晰架构：

• 模块化设计：基于特性的工具组织
• 类型安全性：使用Zod验证的全TypeScript实现
• 可重用组件：通用模式构建器消除代码重复
• 自动注册：工具自动发现和注册
• 错误处理：带有描述性消息的综合错误管理

🔧 开发者体验：

• 易于扩展：添加新工具的简单模式
• 可维护代码：明确的关注点分离
• 文档：自文档化的模式定义
• 调试：详细的日志记录和错误报告

🚀 快速开始

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

🔧 Claude Desktop 集成

要将此MCP服务器与Claude Desktop一起使用，请将其添加到您的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"]
    }
  }
}

📖 使用示例

一旦与Claude Desktop集成，您可以使用自然语言命令：

"播放我的Discover Weekly播放列表"
"搜索The Beatles的歌曲"
"将这首歌添加到我的最爱"
"跳到下一首曲目"
"创建一个名为'Morning Vibes'的新播放列表"
"搜索带有放松音乐的播放列表"
"显示我本月的热门艺术家"
"现在播放什么？"
"将这首歌添加到我的队列"
"获取我最近播放的曲目"
"显示这首歌的歌词"
"获取纯文本歌词以供分析"

🏗️ 项目架构

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听音乐吧！ 🎵🤖