星战科技xingzhan.cloud
返回市场
Spotify MCP 服务器

Spotify MCP 服务器

作者：KaanCL1 星标更新：2025-05-05
安装使用来源：spider==github.com

项目介绍

🎵 Spotify MCP Server

欢迎来到Spotify MCP Server！
该项目允许AI助手和其他客户端通过标准化协议使用模型-上下文-协议（MCP）架构来控制Spotify播放。

🚦 什么是MCP？

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

✨ 功能

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

🛠️ 先决条件

  • Python 3.11或更高版本
  • Spotify Premium账户
  • 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应用中获取Client ID和Client Secret
  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工具：

工具名称描述参数
search在Spotify上查找歌曲query: str
start_playback播放特定歌曲track_name: str
pause_playback暂停当前正在播放的歌曲无
resume_playback恢复暂停的播放无
next_track跳到下一曲无
previous_track返回至上一曲无
get_user_playlists查看您的Spotify播放列表无
set_player_volume调整音量volume: int (0-100)
current_playback获取当前播放的信息无
get_current_user获取用户资料信息无

🧩 工具文档

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

  • search(query: str) → dict
    根据查询字符串在Spotify上搜索曲目。返回最多5个匹配的曲目，每个曲目包含名称、艺术家、专辑、URI和Spotify URL。

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

  • pause_playback() → dict
    暂停活动设备上的当前播放。

  • resume_playback() → dict
    如果已暂停，则恢复播放。

  • next_track() → dict
    跳到当前播放列表或队列中的下一曲。

  • previous_track() → dict
    返回至上一曲。

  • get_user_playlists() → dict
    获取用户的播放列表，包括名称、URL、ID和曲目数量。

  • set_player_volume(volume: int) → dict
    设置Spotify播放器的音量（0-100）。

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

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

🤖 MCP客户端示例

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

from mcp.client import MCPClient

# 连接到MCP服务器
client = MCPClient("http://localhost:8080")

# 搜索一首歌
results = client.call("search", {"query": "Money Trees"})
print(results)

# 播放一首歌
client.call("start_playback", {"track_name": "Money Trees"})

# 暂停播放
client.call("pause_playback")

# 获取当前播放信息
playback_info = client.call("current_playback")
print(playback_info)

⚠️ 错误处理

所有API响应均以JSON对象形式返回。
如果发生错误，响应将包含一个带有描述性消息的 "error" 键。
示例：

{ "error": "未找到曲目：未找到与您的查询匹配的曲目。" }

或

{ "error": "未找到活动设备：请在设备上打开Spotify并重试。" }

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

错误处理内部机制

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

🏗️ 架构图

graph TD
    A[MCP 客户端] -- HTTP --> B[FastMCP 服务器]
    B -- Python 调用 --> C[spotify.py]
    C -- REST API --> D[Spotify Web API]

🧠 工作原理：MCP架构

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

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

🧩 代码质量与可维护性

  • 枚举：用于Spotify范围和错误类型，以提高清晰度和类型安全性。
  • 集中式错误处理：所有错误均使用实用函数进行格式化，以保持一致性。
  • DRY原则：常见的检查（如活动设备）被分解为实用函数。
  • 类型提示：所有函数均使用Python类型提示，以改善代码分析和编辑器支持。
  • 详尽的文档字符串：每个函数和类都有文档，以提高清晰度。
  • 可扩展性：通过在spotify.py中定义新函数并使用@mcp.tool()注册，即可添加新的MCP工具。

🧩 扩展服务器

要添加新的Spotify功能：

  1. 在spotify.py中实现一个新的函数，带有适当的错误处理和文档字符串。
  2. 在main.py中使用@mcp.tool()装饰器注册该函数。
  3. 在此README中记录新工具。

开发者注释：
所有MCP工具设计为返回Python字典，便于与Web API或前端客户端集成。
要扩展功能，只需按照上述模式添加新的@mcp.tool()函数。
对于调试或日志记录，可以在每个工具内打印或记录响应。
所有工具提供类型提示和详细的文档字符串，以增强代码清晰度、可维护性和可发现性（尤其是在IDE中）。
确保spotify模块实现了所需的API交互。
对于身份验证和授权，确保Spotify API凭证在您的环境中正确配置。

🔒 安全注意事项

  • 您的Spotify凭证存储在本地的.env文件中
  • .env文件通过.gitignore排除在git之外
  • 默认情况下，MCP服务器仅接受来自localhost的连接
  • 切勿将凭证提交到版本控制系统！

🧩 故障排除

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

👨‍💻 开发者与贡献说明

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

📚 参考文献