AI导哈

音乐自动化服务

Spotify MCP Server 是一个连接 Spotify 账户与 AI 工具的音乐自动化服务，支持音乐搜索、播放列表管理、个性化推荐和播放控制等功能，适用于音乐爱好者和开发者。

  • by tylerpina
  • TypeScript
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 Tdp2003/spotify-mcp

使用说明

Spotify MCP服务器

将您的Spotify帐户连接到AI工具，并使用模型上下文协议（MCP）自动化您的音乐体验。

这 Spotify MCP服务器 实现 模型上下文协议 使用Cursor、Claude、VS Code等人工智能工具连接您的Spotify帐户。它使AI模型能够通过自然语言指令搜索、分析和管理您的Spotify音乐库、播放列表和播放。

✨ 主要特点

  • 🎵 音乐搜索与发现：查找曲目、专辑、艺术家、播放列表、节目和剧集
  • 📝 播放列表管理：查看、创建、更新、重新排序和管理播放列表
  • 📚 用户库访问：访问和修改您保存的曲目、相册和节目
  • 🎯 个性化推荐：根据您的喜好获取音乐建议
  • 📊 音频分析：检索曲目的音频特征（可跳舞性、能量、节奏等）
  • 🎧 回放控制：（仅限高级版）播放、暂停、跳过和控制播放设备
  • 📈 用户洞察：查看您的热门曲目、艺术家和收听历史记录
  • 🔄 队列管理：将曲目添加到队列中并查看即将播放的歌曲
  • 📱 设备管理：在设备之间传输播放

🚀 快速入门指南

先决条件

  • Spotify帐户（播放控制需要付费）
  • Spotify API证书（见下文）
  • Node.js 18或更新版本

步骤1：获取Spotify API证书

  1. 转到 Spotify开发者仪表板
  2. 创建新应用程序
  3. 注意你的 客户端ID 和 客户端密钥
  4. 设置 重定向URI 致： http://127.0.0.1:8000/callback

步骤2：设置环境变量

创建一个 .env 项目根目录中的文件：

SPOTIFY_CLIENT_ID=your-client-id
SPOTIFY_CLIENT_SECRET=your-client-secret
SPOTIFY_REDIRECT_URI=http://127.0.0.1:8000/callback

备注：您不再需要手动获取访问令牌！服务器将自动处理OAuth流。

步骤3：安装并运行

# Install dependencies
npm install

# Build the server
npm run build

# Start the server
npm start

第四步：使用人工智能工具进行连接

将此配置添加到您的MCP兼容应用程序中（例如Cursor）：

{
  "mcpServers": {
    "spotify": {
      "command": "npx",
      "args": ["-y", "@tdp2003/spotify-mcp@latest"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your-client-id",
        "SPOTIFY_CLIENT_SECRET": "your-client-secret",
        "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:8000/callback"
      }
    }
  }
}

步骤5：完成授权

  1. 打电话给 get_initial_context AI应用程序中的工具
  2. 如果尚未授权，您将收到一个授权URL
  3. 在浏览器中打开URL并登录Spotify
  4. 授权应用程序-您将被自动重定向
  5. 呼叫 get_initial_context 再次确认连接

🛠️ 可用工具

⚠️ 重要：总是打电话 get_initial_context 在使用任何其他工具之前，请先初始化您的Spotify连接。

🔧 背景和设置

get_initial_context

必需的第一步 -初始化您的Spotify连接并提供使用说明。必须在执行任何其他操作之前调用此工具。

它的作用：

  • 验证您的Spotify API证书
  • 如果需要，启动OAuth流
  • 检索您的用户配置文件和帐户信息
  • 提供连接状态和可用功能
  • 返回AI助手的使用说明

📝 播放列表操作

get_user_playlists

检索当前用户或特定用户的播放列表。

参数：

  • limit （可选）：要返回的播放列表数量（1-50，默认值：20）
  • offset （可选）：要返回的第一个播放列表的索引（默认值：0）
  • userId （可选）：获取播放列表的用户ID（默认为当前用户）

退货： 播放列表元数据，包括名称、描述、曲目计数、隐私设置和所有者信息。

create_playlist

使用可自定义的设置创建新的播放列表。

参数：

  • name （必填）：播放列表名称
  • description （可选）：播放列表描述
  • public （可选）：播放列表是否为公共（默认值：false）
  • collaborative （可选）：播放列表是否协作（默认值：false）
  • userId （可选）：要为其创建播放列表的用户ID（默认为当前用户）

退货： 已创建播放列表详细信息，包括Spotify URI和ID。

update_playlist_details

更新播放列表元数据，包括名称、描述、隐私设置和协作状态。

参数：

  • playlistId （必填）：Spotify播放列表ID
  • name （可选）：新播放列表名称
  • description （可选）：新播放列表描述
  • public （可选）：新的公共/私人设置
  • collaborative （可选）：新的协作设置

退货： 更新了带有更改摘要的播放列表详细信息。

add_tracks_to_playlist

通过精确的位置控制将曲目添加到播放列表中。

参数：

  • playlistId （必填）：Spotify播放列表ID
  • uris （必填）：Spotify曲目URI数组（最多100个）
  • position （可选）：插入轨迹的位置（默认为结束）

退货： 使用快照ID和更新的曲目计数进行确认。

remove_tracks_from_playlist

使用精确控制从播放列表中删除曲目。

参数：

  • playlistId （必填）：Spotify播放列表ID
  • tracks （必填）：带有URI和可选位置的跟踪对象数组
  • snapshot_id （可选）：用于并发安全的播放列表快照ID

退货： 确认快照ID和删除详细信息。

reorder_playlist_tracks

通过将一系列曲目移动到新位置来重新排序播放列表中的曲目。

参数：

  • playlistId （必填）：Spotify播放列表ID
  • range_start （必填）：要移动的轨道的起始位置
  • range_length （必填）：要移动的轨道数量
  • insert_before （必填）：将轨道移动到的位置
  • snapshot_id （可选）：用于并发安全的播放列表快照ID

退货： 使用快照ID和重新排序详细信息进行确认。

🔍 音乐搜索与发现

search

在Spotify的目录中搜索专辑、艺术家、曲目、播放列表、节目和剧集。

参数：

  • query （必填）：搜索查询字符串
  • type （可选）：内容类型过滤器（曲目、专辑、艺术家、播放列表、节目、剧集）
  • limit （可选）：结果数量（1-50，默认值：20）
  • offset （可选）：结果偏移（默认值：0）
  • market （可选）：特定市场结果的国家代码

退货： 每种结果类型的详细元数据，包括分页信息。

get_new_releases

在Spotify上获取新专辑发行。

参数：

  • limit （可选）：发布次数（1-50，默认值：20）
  • offset （可选）：结果偏移（默认值：0）
  • country （可选）：区域发布的国家代码

退货： 最近发布的专辑，包含艺术家信息、发布日期和元数据。

get_featured_playlists

从Spotify的编辑团队获取特色播放列表。

参数：

  • limit （可选）：播放列表数量（1-50，默认值：20）
  • offset （可选）：结果偏移（默认值：0）
  • country （可选）：区域内容的国家代码
  • locale （可选）：描述语言/地区

退货： 精心策划的播放列表在Spotify上突出显示，并附有描述和元数据。

👤 用户库和见解

get_user_top_items

根据计算出的亲和力获取当前用户的顶级艺术家或曲目。

参数：

  • type （必填）：项目类型（“艺术家”或“曲目”）
  • time_range （可选）：时间范围（“短期”~4周，“中期”~6个月，“长期”~1年）
  • limit （可选）：项目数（1-50，默认值：20）
  • offset （可选）：结果偏移（默认值：0）

退货： 用户的热门项目，包括流行度评分和元数据。

🎧 播放控制（仅限高级版）

注意：这些工具需要Spotify Premium帐户

get_current_playback

获取当前播放曲目和设备信息。

退货： 当前播放状态，包括曲目、设备和队列信息。

playback_control

控制播放（播放、暂停、跳过、音量）。

参数：

  • action （必填）：播放动作（播放、暂停、下一个、上一个、音量）
  • device_id （可选）：目标设备ID
  • volume_percent （可选）：音量级别（0-100，用于音量操作）

退货： 确认播放动作。

queue_management

将曲目添加到队列并查看即将播放的曲目。

参数：

  • action （必填）：队列操作（'add'或'get'）
  • uris （可选）：跟踪要添加的URI（用于“添加”操作）
  • device_id （可选）：目标设备ID

退货： 队列信息或轨道添加确认。

device_management

在设备之间传输播放。

参数：

  • device_id （必填）：目标设备ID
  • play （可选）：是否在传输时开始播放（默认值：false）

退货： 设备转移确认。

📊 音频分析

get_audio_features

检索曲目的音频功能。

参数：

  • track_ids （必填）：Spotify曲目ID数组

退货： 音频功能包括：

  • 舞蹈性：多么适合跳舞（0.0-1.0）
  • 能量：强度和功率（0.0-1.0）
  • 特殊性：口语出现（0.0-1.0）
  • 声学：轨道是否有声（0.0-1.0）
  • 乐器：曲目是否没有人声（0.0-1.0）
  • 活性：观众在场（0.0-1.0）
  • 价：音乐积极性/幸福感（0.0-1.0）
  • 节奏：速度（每分钟节拍数（BPM））

⚙️ 环境变量

变量 描述 必填
SPOTIFY客户端ID ✅
SPOTIFY客户端机密 ✅
SPOTIFY重定向URI（使用http://127.0.0.1:8000/callback) ✅
SPOTIFY_API_TOKEN SPOTIFY访问令牌（通过OAuth获得） ❌*
SPOTIFY刷新令牌（通过OAuth获得） ❌*
MAX_TOOL_TOKEN_OUTPUT 工具响应的最大令牌输出（默认50000） ❌

*当您首次使用服务器时，这些令牌将通过OAuth流自动获得。

👥 用户角色

  • 开发者：完全访问所有工具和功能
  • 编辑：仅限于以内容为中心的工具（无管理功能）

如果支持，请在MCP客户端配置中设置角色。

📦 Node.js环境设置

如果使用Node版本管理器(nvm, mise, fnm等），您可能需要创建符号链接，以便MCP服务器可以访问Node.js：

sudo ln -sf "$(which node)" /usr/local/bin/node && sudo ln -sf "$(which npx)" /usr/local/bin/npx

如果更改节点版本，请更新这些符号链接。用以下方式删除它们：

sudo rm /usr/local/bin/node /usr/local/bin/npx

💻 发展

安装依赖项：

npm install

在开发模式下构建和运行：

npm run dev

构建服务器：

npm run build

运行内置服务器：

npm start

🧑‍💻 调试

您可以使用MCP检查器进行调试：

npx @modelcontextprotocol/inspector -e SPOTIFY_CLIENT_ID=... -e SPOTIFY_CLIENT_SECRET=... -e SPOTIFY_REDIRECT_URI=... -e SPOTIFY_API_TOKEN=... -e SPOTIFY_REFRESH_TOKEN=... node path/to/build/index.js

这提供了一个用于检查和测试可用工具的web界面。

OAuth流

OAuth流程已通过以下安全性和可用性增强进行了改进：

安全改进

  • 状态验证：使用加密安全的随机状态参数来防止CSRF攻击
  • 重定向URI验证：确保重定向URI使用localhost/127.0.0.0.1进行自动令牌交换
  • 正确的错误处理：针对所有OAuth失败场景的全面错误处理

可用性改进

  • 自动打开浏览器：在默认浏览器中自动打开授权URL
  • 更好的用户反馈：在整个过程中清除错误消息和状态更新
  • 服务器正常关闭：完成后正确关闭OAuth回调服务器

使用OAuth助手

这 oauth-helper.js 脚本提供了一种获取Spotify令牌的独立方式：

node src/utils/oauth-helper.js

这将：

  1. 验证您的环境配置
  2. 启动本地回叫服务器
  3. 自动打开浏览器进入Spotify授权页面
  4. 处理回调并将代码交换为令牌
  5. 显示要添加到您的令牌 .env 文件

环境变量

请确保您的重定向URI配置正确：

SPOTIFY_REDIRECT_URI=http://127.0.0.1:8000/callback

重定向URI 必须 使用 localhost 或 127.0.0.1 以使自动令牌交换正常工作。

许可证

麻省理工学院

相关 MCP