Spotify MCP 服务器

🎵 Spotify MCP服务器

欢迎来到 Spotify MCP服务器!
该项目使AI助手和其他客户端能够使用模型上下文协议（MCP）架构通过标准化协议控制Spotify播放。

🚦 什么是MCP？

模型上下文协议（MCP） 是一个框架，允许人工智能模型和助手通过标准化的界面与外部工具和服务进行交互。
该项目将Spotify功能作为MCP工具公开，使其可供任何兼容MCP的客户端访问，包括人工智能助手、机器人等。

✨ 特性

• 🔍 搜索：在Spotify上搜索歌曲
• ▶️ 播放：在活动的Spotify设备上播放歌曲
• ⏸️ 暂停：暂停当前播放的音乐
• ⏭️ 下一曲目：跳到下一首曲目
• ⏮️ 上一曲：返回上一曲目
• 🔊 音量控制：调整播放音量
• 👤 用户信息：获取当前用户信息
• 📋 播放列表：查看您的Spotify播放列表
• 🎵 正在播放：获取当前播放曲目的信息

🛠️ 先决条件

• Python 3.11或更高版本
• Spotify高级帐户
• Spotify开发者证书

⚡ 设置

1. 克隆此存储库：

   复制

   git clone https://github.com/KaanCL/Spotify-MCP-Server.git
   cd Spotify-MCP-Server
   

2. 设置虚拟环境：

   复制

   uv venv
   

3. 安装依赖项：

   复制

   uv sync
   

   如果您需要单独安装Spotipy：

   复制

   pip install spotipy
   

   注： FastMCP和其他依赖项通过以下方式管理 uv sync.

🔑 配置

1. 在以下网址创建Spotify应用程序 Spotify开发者仪表板
2. 从您的Spotify应用程序获取您的客户端ID和客户端密码
3. 创建一个 .env 使用您的凭据在项目根目录中创建文件：
   复制

   CLIENT_ID=your-spotify-client-id
   CLIENT_SECRET=your-spotify-client-secret
   REDIRECT_URI=http://localhost:8888/callback
   

🚀 初始化和首次运行

首次运行MCP服务器时：

1. 浏览器窗口将打开，要求您登录您的Spotify帐户
2. 您需要授权该应用程序才能访问您的Spotify帐户
3. 授权后，您将被重定向到回调URL
4. MCP服务器将初始化并开始监听端口8080上的连接

🏃 用法

运行MCP服务器：

uv run mcp install main.py

服务器将初始化并注册以下MCP工具：

🧩 工具文档

每个MCP工具都是一个Python函数，用 @mcp.tool() 并且被公开为API端点。
所有工具都返回Python字典（或字典列表），以便于JSON序列化和集成。

• 搜索（查询：str）→ dict
  通过查询字符串在Spotify上搜索曲目。最多返回5首匹配的曲目，每首曲目都有名称、艺术家、专辑、URI和Spotify URL。

• start_playback（track_name:str）→ dict
  开始播放给定的曲目名称。搜索曲目并在用户的活动设备上开始播放。

• pause_playback（）→字典
  暂停活动设备上的当前播放。

• resume_playback（）→字典
  如果暂停，则恢复播放。

• next_track（）→字典
  跳到当前播放列表或队列中的下一首曲目。

• previous_track（）→字典
  返回上一条轨道。

• get_user_playlists（）→字典
  检索用户的播放列表，包括姓名、URL、ID和曲目计数。

• set_player_volume（卷：int）→ dict
  设置Spotify播放器的音量（0-100）。

• current_playback（）→字典
  获取当前播放曲目的信息，包括播放状态、曲目名称、艺术家、专辑、进度和持续时间。

• get_current_user（）→字典
  获取当前Spotify用户的个人资料信息（显示名称、电子邮件、用户ID）。

🤖 MCP客户端示例

任何兼容MCP的客户端都可以与此服务器交互，包括AI助手和编程客户端：

from mcp.client import MCPClient

# Connect to the MCP server
client = MCPClient("http://localhost:8080")

# Search for a song
results = client.call("search", {"query": "Money Trees"})
print(results)

# Play a song
client.call("start_playback", {"track_name": "Money Trees"})

# Pause playback
client.call("pause_playback")

# Get current playback info
playback_info = client.call("current_playback")
print(playback_info)

⚠️ 错误处理

所有API响应都作为JSON对象返回。
如果发生错误，响应将包括 "error" 带有描述性信息的按键。
示例：

{ "error": "No tracks found: No tracks found for your query." }

或

{ "error": "No active device found: Please open Spotify on a device and try again." }

提示： 始终检查 "error" 在使用数据之前键入响应。

错误处理内部

• 使用实用函数对错误进行标准化(format_error)和枚举(SpotifyError)为了清晰和可维护性。
• 常见的错误场景包括：没有活动设备、找不到曲目、没有播放、音量无效和身份验证错误。
• 所有错误都以一致的格式返回，以便于客户端处理。

🏗️ 架构图

graph TD
    A[MCP Client] -- HTTP --> B[FastMCP Server]
    B -- Python Call --> C[spotify.py]
    C -- REST API --> D[Spotify Web API]

🧠 工作原理：MCP架构

1. MCP服务器：注册工具并处理请求。
2. FastMCP实施：将FastMCP用于轻量级、高性能的服务器。
3. Spotify集成：使用Spotify连接到Spotify API。
4. 工具注册：每个Spotify功能都注册为具有类型提示和文档的MCP工具。

MCP服务器通过标准化协议公开这些工具，允许AI模型和其他客户端发现和调用这些工具，而无需了解Spotify API的底层实现细节。

🧩 代码质量和可维护性

• 枚举：用于Spotify范围和错误类型，以提高清晰度和类型安全性。
• 集中错误处理：所有错误都使用实用函数进行格式化，以保持一致性。
• 干燥原理：常用检查（如活动设备）被纳入实用功能。
• 类型提示：所有函数都使用Python类型提示，以获得更好的代码分析和编辑器支持。
• 综合文档字符串：为了清楚起见，每个函数和类都有文档记录。
• 可扩展：通过在中定义函数来添加新的MCP工具 spotify.py 并将其注册到 @mcp.tool().

🧩 扩展服务器

要添加新的Spotify功能：

1. 在中实现新功能 spotify.py 通过适当的错误处理和文档字符串。
2. 将该功能注册为MCP工具 main.py 使用 @mcp.tool() 装饰师。
3. 在README中记录新工具。

开发者说明：
所有MCP工具都旨在返回Python字典，以便于JSON序列化和与web API或前端客户端的集成。
要扩展功能，只需添加新的 @mcp.tool() 函数遵循与上述相同的模式。
对于调试或日志记录，您可以在每个工具中打印或记录响应。
为所有工具提供类型提示和详细的文档字符串，以提高代码的清晰度、可维护性和可发现性（特别是在IDE中）。
确保 spotify 模块实现了所需的API交互。
对于身份验证和授权，请确保在您的环境中正确配置Spotify API凭据。

🔒 安全说明

• 您的Spotify凭据存储在本地 .env 文件
• 这 .env 文件通过从git中排除 .gitignore
• 默认情况下，MCP服务器只接受来自localhost的连接
• 永远不要将您的凭据提交给版本控制！

🧩 故障排除

• 未找到活动设备： 确保Spotify在您的设备上打开并处于活动状态。
• 身份验证错误： 仔细检查你的 .env 凭据和Spotify开发者仪表板设置。
• API费率限制： Spotify API有费率限制；避免过多的请求。
• 意外错误： 检查 "error" 键入响应以获取详细信息。

👨‍💻 开发人员和贡献说明

• 所有函数和工具都返回字典或列表，以便于JSON序列化。
• 错误处理一致；始终检查 "error" 作为回应。
• 在中扩展MCP工具 main.py 添加新的Spotify功能。
• 对于调试，根据需要添加日志记录或打印语句。
• 欢迎提出请求和建议！请先打开一个问题，讨论您想更改什么。

📚 参考文献

• Spotify Web API文档
• Spotipy图书馆
• MCP协议