AI导哈

Spotify MCP服务器

一个全面的Spotify操作模型上下文协议(MCP)服务器，提供36个生产就绪的工具和FastMCP传输。

  • by PeterAkande
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 PeterAkande/spotify_mcp

使用说明

Spotify MCP 服务器

一个用于Spotify操作的全面模型上下文协议（MCP）服务器 36款可投入生产的工具 以及FastMCP传输。

🚀 快速入门

先决条件

# Install uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

安装

# Clone and install dependencies
git clone <repository>
cd spotify_mcp
uv sync

开发环境设置

# Copy environment template
cp .env.example .env
# Edit .env with your configuration (see Configuration section)

# Start development server (auto-reload)
uv run python start_server.py
# OR manually with custom port
uvicorn main:app --reload --port 8001

特点/功能

完成Spotify集成

  • 36 MCP 工具 涵盖所有Spotify运营活动
  • OAuth 2.0 认证 带有Spotify令牌验证
  • 类型安全 带有全面的 Pydantic 模型

可用工具（共36个）

🔍 看起来像是一个放大镜的符号，通常用来表示“查看”、“搜索”或“调查”的意思。在中文里，可以简单地翻译为“🔍”（虽然直接使用符号可能无法完全传达其含义，但在此处为保持原文格式，故保留符号形式）。若需文字表达，可译为“放大镜符号”或根据上下文具体翻译为“查看”、“搜索”等。 搜索与发现 （3种工具）

  • search_music - 带有筛选和分页功能的通用音乐搜索
  • get_categories - 浏览可用的音乐类别
  • get_new_releases - 获取新专辑发行信息

📚 书籍 图书馆管理 （8个工具）

  • get_saved_tracks - 获取用户喜欢的曲目，并分页显示
  • get_saved_albums - 获取用户保存的专辑
  • get_followed_artists - 获取关注的艺术家
  • get_recently_played - 获取最近播放的曲目
  • get_top_items - 获取用户的顶级曲目或艺术家
  • save_tracks - 将曲目添加到用户的库中
  • remove_saved_tracks - 从库中移除曲目
  • follow_artists - 关注或取消关注艺术家

🎼 播放列表管理 （8种工具）

  • get_user_playlists - 列出用户播放列表，并分页显示
  • create_playlist - 创建新的播放列表
  • get_playlist - 获取播放列表详情和元数据
  • get_playlist_tracks - 从播放列表中获取曲目
  • add_tracks_to_playlist - 将曲目添加到播放列表
  • remove_tracks_from_playlist - 从播放列表中移除曲目
  • update_playlist_details - 更新播放列表名称、描述等。
  • unfollow_playlist - 取消关注/删除播放列表

🎮 播放控制 （12种工具）

  • get_current_playback - 获取当前播放状态
  • get_devices - 列出可用的Spotify设备
  • start_playback - 启动/继续播放并选择选项
  • pause_playback - 暂停当前播放
  • next_track - 跳到下一曲
  • previous_track - 跳到上一首曲目
  • seek_track - 寻求特定职位
  • set_volume - 控制播放音量
  • set_repeat - 设置重复模式（曲目、上下文、关闭）
  • set_shuffle - 切换随机播放模式
  • transfer_playback - 在设备间传输播放内容
  • add_to_queue - 将曲目添加到播放队列

🔍 翻译为中文是：放大镜（用于查看细节或搜索） 音乐分析 （6种工具）

  • get_track_audio_features - 获取曲目的音频特征
  • get_audio_analysis - 获取详细的音频分析
  • get_artists - 获取艺术家信息
  • get_artist_top_tracks - 获取艺术家最受欢迎的曲目
  • get_artist_albums - 获取艺术家的专辑
  • get_album_tracks - 从专辑中获取曲目

配置

环境变量（.env）

# Server Configuration
SERVER_HOST=0.0.0.0                    # Server bind address
SERVER_PORT=8001                       # Server port
DEBUG=false                            # Enable debug mode

# Spotify OAuth Configuration
SPOTIFY_CLIENT_ID=your_client_id       # From Spotify Developer Dashboard
SPOTIFY_CLIENT_SECRET=your_secret      # From Spotify Developer Dashboard
SPOTIFY_REDIRECT_URI=http://localhost:8080/callback

# Logging
LOG_LEVEL=INFO                         # DEBUG, INFO, WARNING, ERROR

Spotify OAuth 权限范围

服务器需要以下Spotify权限范围：

  • user-read-private - 读取用户资料
  • user-read-email - 阅读用户邮件
  • user-library-read - 读取用户的库
  • user-library-modify - 修改用户的库
  • playlist-read-private - 阅读私人播放列表
  • playlist-modify-public - 修改公共播放列表
  • playlist-modify-private - 修改私人播放列表
  • user-read-playback-state - 读取播放状态
  • user-modify-playback-state - 控制播放
  • user-read-recently-played - 阅读最近播放的内容
  • user-top-read - 阅读热门曲目/艺术家
  • user-follow-read - 阅读关注的艺术家（或：关注的艺术家作品）
  • user-follow-modify - 关注/取消关注艺术家

响应格式

该服务器支持多种响应格式，以实现最佳性能：

紧凑型（默认）

  • 最适合用于通用音乐浏览与人工智能处理
  • 包含基本元数据 + 曲目/艺术家信息
  • 用例最常见的操作

最小的

  • 最适合于列表和枚举
  • 包含仅限ID、姓名、基本信息
  • 用例高流量操作

满的；完整的

  • 最适合于完整的音乐数据
  • 包含所有可用的元数据和详细信息
  • 用例详细的音乐分析

RAW

  • 最适合用于直接Spotify API响应
  • 包含未处理的Spotify API数据
  • 用例高级集成

分页支持

大多数工具都支持灵活的分页功能：

标准分页

# Get first 20 tracks
get_saved_tracks(limit=20, offset=0)

# Get next 20 tracks  
get_saved_tracks(limit=20, offset=20)

示例

# Get user's top tracks from last 6 months
get_top_items(type="tracks", time_range="medium_term", limit=50)

# Search for Drake songs with pagination
search_music(query="Drake", type="track", limit=10, offset=0)

建筑

MCP服务器设计

  • 交通使用HTTP传输的FastMCP
  • 认证Spotify OAuth 2.0（含令牌验证）
  • 格式基于JSON的MCP协议
  • **流媒体（播放）**实时响应处理

OAuth 流程

┌─────────────────────┐    ┌──────────────────────┐    ┌─────────────────┐
│   MCP Client        │    │   Spotify OAuth      │    │  Spotify MCP    │
│                     │    │   (accounts.spotify) │    │  Server         │
│ 1. Request with     │────│ 2. Validates token   │────│ 3. Spotify API  │
│    Bearer token     │    │    Returns user info │    │    operations   │
│                     │    │                      │    │                 │
└─────────────────────┘    └──────────────────────┘    └─────────────────┘

API 参考文档

认证

所有终端点都需要有效的Spotify OAuth令牌：

Authorization: Bearer <spotify_oauth_token>

发展

项目设置

# Install dependencies
uv sync

# Setup environment
cp .env.example .env
# Edit .env file with your configuration

# Run tests
uv run python examples/test_functions.py

# Start development server with auto-reload
uv run python start_server.py

开发命令

# Development server (auto-reload)
uv run python start_server.py

# Manual development with custom port
uvicorn main:app --reload --port 8001

# Production server
uvicorn main:app --host 0.0.0.0 --port 8001

# Run interactive tests
uv run python examples/test_functions.py

测试工具

该项目包括 examples/test_functions.py - 一个交互式测试套件：

  • 测试所有36个Spotify MCP功能
  • 全面调试并报告错误
  • 基于类别的测试（搜索、库、播放列表、播放、分析）

Spotify OAuth 权限范围

服务器会自动配置这些所需的范围：

REQUIRED_SCOPES = [
    "user-read-private",
    "user-read-email", 
    "user-library-read",
    "user-library-modify",
    "playlist-read-private",
    "playlist-modify-public",
    "playlist-modify-private",
    "user-read-playback-state",
    "user-modify-playback-state",
    "user-read-recently-played",
    "user-top-read",
    "user-follow-read",
    "user-follow-modify"
]

🔐 Spotify OAuth 配置

  1. Spotify开发者仪表板

  2. OAuth 配置

    • 复制客户端ID和客户端密钥到 .env 文件
    • 根据您的OAuth流程需求配置重定向URI
    • 下载凭证（不在本服务器上存储）

  3. 令牌验证

    • 这个服务器使用Spotify的（服务）来验证令牌 /v1/me 终端节点
    • 无凭证存储 - 每次请求验证令牌
    • 为了快速测试获取访问令牌，请检查 examples/get_access_token.py

📝 许可证

MIT 许可证 - 详见 LICENSE 文件。

相关 MCP