AI导哈

Spotify OAuth MCP服务器

基于Cloudflare Workers的Spotify OAuth 2.0集成MCP服务器，支持OAuth发现和动态客户端注册，用于AI代理与Spotify Web API的交互。

  • by LibreChat-AI
  • TypeScript
  • 本地部署
  • 12 星标
  • 更新于
在 GitHub 查看 LibreChat-AI/spotify-mcp

使用说明

Spotify MCP OAuth服务器

这是一把叉子 Stytch的MCP消费者TODO列表 示例，用于演示使用Cloudflare Workers将Spotify OAuth 2.0与模型上下文协议（MCP）集成。

为什么是这个叉子？

最初的Stytch示例为MCP服务器实现OAuth发现和动态客户端注册提供了良好的基础。我们将此项目分叉为：

  1. 利用OAuth发现模式：原始实现展示了如何创建与MCP Inspector配合使用的OAuth发现端点
  2. 用Spotify取代Stytch：演示如何与本机不支持动态客户端注册的第三方OAuth提供商（Spotify）集成
  3. 关注API层：虽然最初的版本包括一个带有前端组件的完整TODO应用程序，但这个分支主要关注MCP服务器的实现

发生了什么变化

API层更新

  • 添加新文件:

    • api/SpotifyMCP.ts -Spotify Web API的MCP服务器实现
    • api/SpotifyService.ts -Spotify API交互服务层
    • api/lib/spotify-auth.ts -Spotify的OAuth流实现

  • 修改文件:

    • api/index.ts -已更新以处理Spotify OAuth流和MCP端点
    • 环境变量从Stytch更改为Spotify凭据

主要特点

该实施提供了：

  • OAuth 2.0授权代码流 支持PKCE
  • OAuth发现端点 在 /.well-known/oauth-authorization-server
  • 动态客户端注册 MCP检查器兼容性
  • 自动令牌刷新 当访问令牌过期时
  • Spotify Web API全面集成 通过MCP工具
  • Cloudflare持久对象 用于MCP服务器状态管理

建筑

该项目使用：

  • Cloudflare员工 用于后端API
  • Cloudflare持久对象 对于MCP服务器实例
  • Spotify Web API 用于音乐数据和播放控制
  • 模型上下文协议（MCP） 用于AI代理集成

重要提示：开发示例

⚠️ 此服务器主要用于使用MCP客户端开发和测试OAuth流。

此实现针对以下方面进行了优化：

  • 测试与 自由聊天 -支持MCP的开源AI聊天平台
  • 发展与 MCP检查员 -官方MCP调试工具
  • 学习如何为MCP服务器实现OAuth发现

可生产的

在部署到生产环境之前，您应该：

  1. 添加身份验证

    • 在中实施适当的客户端验证 /register 端点
    • 添加速率限制以防止滥用
    • 针对白名单验证重定向 URI

  2. 增强安全性

    • 实施CSRF保护
    • 添加请求签名/验证
    • 使用安全会话管理
    • 实施适当的错误处理，不会泄露敏感信息

  3. 添加监控和日志记录

    • 实施全面日志记录
    • 添加错误跟踪（例如哨兵）
    • 监控API使用情况和费率限制
    • 跟踪OAuth流完成率

  4. 优化规模

    • 实施缓存策略
    • 添加用于持久存储的数据库（而不是用于生产数据的KV）
    • 实施适当的连接池
    • 为速率受限的操作添加请求队列

  5. 手柄边缘案例

    • 使用指数回退实现适当的重试逻辑
    • 处理Spotify API维护窗口
    • 为非关键功能添加优雅的降级
    • 实施适当的超时处理

什么已经准备好生产了

由于最初的Stytch实现，该项目已经包括：

✅ Cloudflare员工部署

  • 完整Workers配置 wrangler.jsonc
  • MCP服务器实例的持久对象设置
  • 工人KV集成数据存储
  • Workers环境的正确TypeScript配置

✅ 基础设施基金会

  • 用于实时MCP通信的SSE（服务器发送事件）实现
  • 正确处理CORS
  • 环境变量管理
  • 构建和部署脚本

这意味着您已经拥有了坚实的基础设施基础，只需添加上述安全和监控层即可用于生产。

生产部署检查表

如果您计划在生产中使用此功能：

  • []审查并实施所有安全考虑因素
  • []添加全面的错误处理
  • []实施适当的日志记录和监控
  • []添加自动测试
  • []设置CI/CD管道
  • []安全地配置生产环境变量
  • []实施备份和恢复程序
  • []添加API版本控制策略
  • []为您的具体实施创建文档
  • []实施用户同意和数据隐私合规

MCP检查器兼容性

遵循以下模式 PayPal的MCP服务器，此实现提供：

  1. OAuth发现 在 /.well-known/oauth-authorization-server
  2. 动态客户端注册 在 /register 端点
  3. 授权代理 重定向到Spotify的OAuth系统

这允许MCP Inspector和其他MCP客户端自动发现并向我们的服务器注册，即使Spotify本身不支持动态客户端注册。

设置

1.创建Spotify应用程序

  1. 首选 Spotify开发者仪表板
  2. 创建新应用程序
  3. 记下您的客户端ID和客户端密码
  4. 为您的应用程序添加重定向URI（例如。， http://localhost:3000/callback)

2.配置环境变量

创建一个 .dev.vars 文件基于 .dev.vars.template:

SPOTIFY_CLIENT_ID=your_spotify_client_id
SPOTIFY_CLIENT_SECRET=your_spotify_client_secret

3.安装依赖项

npm install

4.本地运行

npm run dev

MCP服务器将在 http://localhost:3000/sse

Vite的环境变量

这 vite.config.ts 文件支持用于开发的其他环境变量：

  • VITE_PORT：自定义开发服务器端口（默认值：3000）

    VITE_PORT=8080 npm run dev

  • VITE_ALLOWED_HOSTS：为开发服务器指定允许的主机（在使用隧道服务时很有用）

    VITE_ALLOWED_HOSTS="localhost,your-ngrok-domain.ngrok-free.app" npm run dev

HTTPS要求

问题

Spotify Web API要求OAuth回调使用HTTPS，现代浏览器强制MCP客户端和服务器之间的安全连接，以防止混合内容问题。

按部署类型列出的解决方案

生产部署（推荐）

✅ Cloudflare工人解决方案

  • MCP服务器：部署到Cloudflare Workers-包括自动HTTPS

    • 您部署的服务器： https://your-worker.workers.dev
    • 永久、稳定的HTTPS URL
    • 无需额外的SSL配置
    • 全球边缘网络，响应时间快

  • MCP客户端：大多数生产MCP客户端已经通过HTTPS运行

  • Spotify应用程序：更新重定向URI以使用您的Workers域（一次性设置）

# Deploy to get permanent HTTPS URL
npm run deploy

# Update Spotify app redirect URI to:
# https://your-worker.workers.dev/callback

地方发展

🔧 本地测试的ngrok解决方案

在本地开发时，使用 ngrok 要创建HTTPS隧道，请执行以下操作：

1.安装ngrok
# Download from https://ngrok.com/download or use package manager
brew install ngrok  # macOS
# or
snap install ngrok  # Linux
2.启动本地MCP服务器
# Start with allowed hosts configuration
VITE_ALLOWED_HOSTS="localhost,*.ngrok-free.app" npm run dev
3.创建HTTPS隧道

对于本地开发，您可能需要服务器和客户端的隧道：

# Terminal 1: Tunnel for MCP Server (port 3000)
ngrok http 3000

# Terminal 2: Tunnel for LibreChat if running locally (port 3080)
ngrok http 3080
4.配置开发会话

启动ngrok后，您将获得临时HTTPS网址：

  • MCP服务器： https://abc123.ngrok-free.app
  • 免费聊天： https://def456.ngrok-free.app

为此开发会话更新您的Spotify应用程序：

  1. 首选 Spotify开发者仪表板
  2. 添加 ngrok 重定向 URI: https://abc123.ngrok-free.app/callback
  3. 配置MCP客户端以使用： https://abc123.ngrok-free.app/sse

比较：生产与发展

方面 Cloudflare员工（生产） ngrok（开发）
超文本传输安全协议 ✅ 自动、永久 ✅ 临时隧道
网址 ✅ 稳定、持久 ❌ 重新启动时更改
设置 ✅ 一次性部署 ❌ 每次会话设置
成本 ✅ 免费套餐可用 ✅ 免费套餐可用
演出 ✅ 全球边缘网络 ❌ 隧道架空
用例 生产、永久测试 本地开发

推荐工作流程

  1. 从生产开始：首先部署到Cloudflare Workers进行稳定测试
  2. 需要时使用本地：仅当需要测试本地代码更改时才使用ngrok
  3. 混合方法：保持生产部署以进行稳定测试，使用本地进行主动开发

ngrok限制（仅限开发）

  • 临时域名：每次重新启动时URL都会更改（需要更新Spotify应用程序）
  • 会话限制：2小时免费课程
  • 请求限制：免费套餐每分钟40个请求
  • 多隧道：服务器和客户端需要单独的ngrok实例

生产注意事项

✅ Cloudflare员工福利：

  • 具有有效证书的自动HTTPS
  • 全球CDN实现低延迟
  • 内置DDoS防护
  • 99.9%正常运行时间SLA
  • 轻松的自定义域支持

供企业使用：

  • 自定义域： mcp.yourcompany.com
  • Cloudflare WAF增强了安全性
  • 高级分析和监控
  • 团队协作功能

OAuth流

如何使用MCP检查器

  1. 发现：MCP检查器获取 /.well-known/oauth-authorization-server
  2. 注册：检查员在 /register 端点
  3. 授权：用户被重定向到 /authorize，重定向到Spotify
  4. 使用者同意：用户在Spotify页面上授权
  5. 代币交换：检查员交换代码 /token
  6. 访问MCP：检查器使用令牌通过SSE访问MCP端点

可用的MCP工具

Spotify MCP服务器提供以下工具：

搜索

  • searchTracks -搜索曲目
  • searchArtists -寻找艺术家
  • searchAlbums -搜索相册
  • searchPlaylists -搜索播放列表

用户档案

  • getCurrentUserProfile -获取当前用户的个人资料

回放控制

  • getCurrentPlayback -获取当前播放状态
  • pausePlayback -暂停播放
  • resumePlayback -恢复播放
  • skipToNext -跳到下一首曲目
  • skipToPrevious -跳至上一曲目

播放列表

  • getUserPlaylists -获取用户的播放列表
  • getPlaylistTracks -从播放列表中获取曲目
  • createPlaylist -创建新的播放列表
  • addTracksToPlaylist -将曲目添加到播放列表

用户数据

  • getRecentlyPlayed -获取最近播放的曲目
  • getTopTracks -获取用户的热门曲目
  • getTopArtists -获取用户的顶级艺术家

示例用法

使用MCP检查器

  1. 打开MCP检查器：
    npx @modelcontextprotocol/inspector@latest
  2. 将传输类型设置为 SSE
  3. 输入URL: http://localhost:3000/sse
  4. 单击连接
  5. 重定向时遵循OAuth流程

手动令牌使用

如果您希望绕过OAuth流进行测试：

  1. 使用手动流程获取令牌
  2. 在MCP检查器中，添加标题：
    • Authorization: Bearer YOUR_ACCESS_TOKEN
    • X-Spotify-Refresh-Token: YOUR_REFRESH_TOKEN

部署

快速部署到Cloudflare Workers

🚀 自动HTTPS解决方案

部署到Cloudflare Workers会自动解决HTTPS要求：

# 1. Set your Spotify credentials
wrangler secret put SPOTIFY_CLIENT_ID
wrangler secret put SPOTIFY_CLIENT_SECRET

# 2. Deploy (gets automatic HTTPS)
npm run deploy

# 3. Update Spotify app redirect URI to your new Workers URL
# Example: https://your-worker.workers.dev/callback

您的MCP服务器将在以下网址提供： https://your-worker.workers.dev/sse

⚠️ 记住：这是一个开发示例。有关生产注意事项，请参阅上面的“重要：开发示例”部分。

生产部署

实际生产使用：

  1. 分叉此存储库
  2. 实施上面列出的安全增强功能
  3. 添加适当的监控和错误处理
  4. 考虑使用Cloudflare的付费功能：
    • 持久对象，用于更好的状态管理
    • 缓存工人KV
    • 利率限制规则
    • Web应用程序防火墙（WAF）

安全考虑

  1. 客户端凭据：切勿在客户端代码中暴露您的Spotify客户端密码
  2. 令牌存储：安全地存储令牌，并对所有通信使用HTTPS
  3. 范围：仅请求应用程序所需的最小范围
  4. PKCE：该实现支持PKCE以增加安全性
  5. 客户注册：在生产中，考虑向注册端点添加验证

Spotify API Gotchas

1.HTTPS要求

  • Spotify Web API需要HTTPS进行OAuth回调
  • 解决方案：部署到Cloudflare Workers以实现自动HTTPS
  • 地方发展：使用ngrok进行HTTPS隧道
  • 当客户端和服务器使用不同的协议时，会出现混合内容错误

2.主动设备要求

  • 播放控制端点(pausePlayback, resumePlayback等）需要活动的Spotify设备
  • 用户必须在至少一个设备（桌面应用程序、移动设备或网络播放器）上打开Spotify
  • 如果没有可用的设备，API返回404“未找到活动设备”

3.高级账户限制

  • 许多播放控制功能需要Spotify Premium帐户
  • 免费帐户可以读取数据，但无法控制播放
  • API为免费帐户返回403个“高级要求”错误

4.费率限制

  • Spotify对所有端点实施速率限制
  • 限制因端点而异，但通常允许每分钟180个请求
  • 对429（太多请求）响应实施指数回退

5.令牌到期

  • 访问令牌在1小时后过期
  • 此实现处理自动刷新，但确保存储刷新令牌
  • 如果长时间未使用，刷新令牌可能会失效

6.范围要求

  • 不同的端点需要不同的OAuth作用域
  • 缺少作用域导致403个禁止错误
  • 常见要求范围：
    • user-read-private -用户配置文件访问
    • user-read-playback-state -当前播放信息
    • user-modify-playback-state -播放控制
    • playlist-read-private -访问用户播放列表
    • playlist-modify-public -创建/修改播放列表

7.市场限制

  • 某些内容受到地理市场的限制
  • API可能会根据用户的国家/地区返回不同的结果
  • 使用 market 搜索以获得适合区域的结果时的参数

致谢

这个项目是基于优秀 Stytch MCP消费者TODO列表 示例，演示了如何为MCP服务器实现OAuth发现。我们已经调整了他们的模式，使其与Spotify的OAuth系统兼容。

资源

相关 MCP