AI导哈

Spotify MCP服务器

一个生产就绪的Spotify模型上下文协议服务器，提供稳健的错误处理和令牌管理功能。

  • by thebigredgeek
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 thebigredgeek/spotify-mcp-server

使用说明

Spotify MCP服务器

用于Spotify的生产就绪模型上下文协议（MCP）服务器，具有防弹错误处理和令牌管理功能。

特性

  • 🔐 一次性OAuth身份验证 -认证一次，永远使用（如spotifyd）
  • 🛡️ 防弹错误处理 -永远不会在瞬态故障时使令牌无效
  • 🔄 自动令牌刷新 -通过并发请求重复数据删除实现无缝刷新
  • 💾 原子证书存储 -防止进程崩溃时出现损坏
  • ⚡ 智能重试逻辑 -具有速率限制处理的指数回退
  • 🎯 保守的代币管理 -仅在可证明无效时清除凭据

示例用法

设置后，您可以使用Claude的自然语言提示来控制Spotify：

🎵 搜索与发现

"Search for AC/DC songs"
"Find albums by The Beatles"
"Search for rock playlists"
"Find tech podcasts"
"Search for The Beatles - show me tracks, albums, and playlists"

▶️ 回放控制

"Play Back in Black by AC/DC"
"Play the album Highway to Hell"
"Play my Discover Weekly playlist"
"Pause the music"
"Skip to the next song"
"Go back to the previous track"
"What's currently playing?"

🎚️ 高级控制

"Set volume to 50%"
"Turn on shuffle"
"Enable repeat"
"Set repeat to one song only"
"Turn off repeat"

📱 设备管理

"Show my Spotify devices"
"Switch playback to my phone"
"Transfer playback to my speaker"

所有这些操作都与自动令牌刷新、速率限制和错误恢复无缝协作。

安装

之前：

你需要设置一个Spotify开发者应用程序来获取客户端id和密码。这将用于对MCP服务器进行身份验证。

方法1：基于提示的设置（最简单）

通过Claude CLI安装，让Claude指导您完成安装：

# Install the MCP server
claude mcp add --transport stdio spotify -- npx -y @tbrgeek/spotify-mcp-server

# Restart Claude Code
# (Fully quit and reopen)

服务器在没有凭据的情况下启动，并在需要时提供设置说明。只需问克劳德：

  • “对spotify mcp服务器进行身份验证”

Claude将提供分步设置说明，包括：

  1. 创建Spotify应用程序
  2. 运行身份验证脚本
  3. 配置凭据

看 基于提示的安装指南 详见下文。

方法2：交互式身份验证（存储凭据）

对于重启后仍然有效的持久凭据：

# Install globally
npm install -g @tbrgeek/spotify-mcp-server

# Run authentication
spotify-mcp-server auth

# Add to Claude Code config
claude mcp add --transport stdio spotify -- spotify-mcp-server

看 Claude CLI安装指南 获取完整说明。

方法3：环境变量（高级）

对于共享配置或CI/CD：

# Set environment variables (see docs/CLAUDE_CLI_SETUP.md)
export SPOTIFY_CLIENT_ID="your_client_id"
export SPOTIFY_CLIENT_SECRET="your_client_secret"
export SPOTIFY_REFRESH_TOKEN="your_refresh_token"
export SPOTIFY_ACCESS_TOKEN="your_access_token"

# Install with environment variables
claude mcp add --transport stdio spotify -- npx -y @tbrgeek/spotify-mcp-server

看 Claude CLI安装指南 用于完整的环境变量设置。

本地开发

git clone https://github.com/thebigredgeek/spotify-mcp-server.git
cd spotify-mcp-server
npm install
npm run build
npm link

设置

1.创建Spotify应用程序

  1. 首选 Spotify开发者仪表板
  2. 创建新应用程序
  3. 注意你的 客户端ID 和 客户端密钥
  4. 添加重定向URI: http://127.0.0.1:8888/callback

2.身份验证

npm run auth

按照提示操作：

  • 输入您的客户端ID和客户端密码
  • 在浏览器中授权
  • 凭据保存到 ~/.spotify-mcp/credentials.json

3.配置MCP客户端

克劳德CLI/克劳德代码（推荐）

编辑 ~/.claude/settings.local.json:

{
  "mcpServers": {
    "spotify": {
      "type": "stdio",
      "command": "spotify-mcp-server"
    }
  }
}

或使用环境变量（请参见 Claude CLI安装指南):

{
  "mcpServers": {
    "spotify": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@tbrgeek/spotify-mcp-server"],
      "env": {
        "SPOTIFY_CLIENT_ID": "${SPOTIFY_CLIENT_ID}",
        "SPOTIFY_CLIENT_SECRET": "${SPOTIFY_CLIENT_SECRET}",
        "SPOTIFY_ACCESS_TOKEN": "${SPOTIFY_ACCESS_TOKEN}",
        "SPOTIFY_REFRESH_TOKEN": "${SPOTIFY_REFRESH_TOKEN}"
      }
    }
  }
}

克劳德桌面

增添 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "spotify": {
      "command": "npx",
      "args": ["-y", "@tbrgeek/spotify-mcp-server"]
    }
  }
}

对于当地发展：

{
  "mcpServers": {
    "spotify": {
      "command": "node",
      "args": ["/Users/YOUR_USERNAME/opensource/spotify-mcp-server/dist/index.js"]
    }
  }
}

基于提示的安装指南

设置Spotify MCP服务器的最简单方法是先安装它，然后让Claude引导您完成身份验证。

步骤1：安装服务器

# Install via Claude CLI
claude mcp add --transport stdio spotify -- npx -y @tbrgeek/spotify-mcp-server

# Restart Claude Code (fully quit and reopen)

第二步：向克劳德询问安装说明

重新启动后，问克劳德以下任何问题：

  • “如何设置Spotify？”
  • “检查Spotify健康状况”
  • “获取Spotify身份验证状态”

Claude将提供详细的设置说明，包括：

创建Spotify应用程序：

  1. 首选https://developer.spotify.com/dashboard
  2. 点击“创建应用”
  3. 填写应用程序名称和重定向URI： http://127.0.0.1:8888/callback
  4. 保存您的客户端ID和客户端密码

正在运行身份验证：

# Install globally
npm install -g @tbrgeek/spotify-mcp-server

# Run authentication
spotify-mcp-server auth

身份验证脚本将：

  • 提示输入您的客户ID和密码
  • 打开浏览器进行授权
  • 将凭据保存到 ~/.spotify-mcp/credentials.json

重新启动Claude代码 -凭据现在已自动加载！

步骤3：验证

问克劳德：“检查Spotify的健康状况”

您应该看到：✅ Spotify MCP服务器已通过身份验证并可运行！

手动配置

如果您更喜欢直接编辑配置文件，请按照以下方式操作：

选项1：使用存储的凭据

  1. 运行身份验证 生成凭据：

    npm install -g @tbrgeek/spotify-mcp-server
spotify-mcp-server auth

  2. 编辑Claude代码配置 在 ~/.claude/settings.local.json:

    {
  "mcpServers": {
    "spotify": {
      "type": "stdio",
      "command": "spotify-mcp-server"
    }
  }
}

  3. 重新启动Claude代码 -凭据从加载 ~/.spotify-mcp/credentials.json

选项2：使用环境变量

  1. 获取您的凭据 （运行一次身份验证以获取刷新令牌）：

    spotify-mcp-server auth
cat ~/.spotify-mcp/credentials.json

  2. 设置环境变量 在您的shell配置文件中(~/.zshrc 或 ~/.bashrc):

    export SPOTIFY_CLIENT_ID="your_client_id_here"
export SPOTIFY_CLIENT_SECRET="your_client_secret_here"
export SPOTIFY_ACCESS_TOKEN="your_access_token_here"
export SPOTIFY_REFRESH_TOKEN="your_refresh_token_here"

  3. 编辑Claude代码配置 在 ~/.claude/settings.local.json:

    {
  "mcpServers": {
    "spotify": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@tbrgeek/spotify-mcp-server"],
      "env": {
        "SPOTIFY_CLIENT_ID": "${SPOTIFY_CLIENT_ID}",
        "SPOTIFY_CLIENT_SECRET": "${SPOTIFY_CLIENT_SECRET}",
        "SPOTIFY_ACCESS_TOKEN": "${SPOTIFY_ACCESS_TOKEN}",
        "SPOTIFY_REFRESH_TOKEN": "${SPOTIFY_REFRESH_TOKEN}"
      }
    }
  }
}

  4. 重新加载外壳 和 重新启动克劳德代码:

    source ~/.zshrc  # or ~/.bashrc

查找配置文件

克劳德代码配置：

~/.claude/settings.local.json  # User-specific (not version-controlled)
~/.claude/settings.json         # Global defaults

Spotify凭据：

~/.spotify-mcp/credentials.json  # Stored credentials (from auth script)

编辑配置：

# macOS/Linux
code ~/.claude/settings.local.json
# or
vim ~/.claude/settings.local.json

编辑任何配置后：

  • 完全退出Claude Code（不仅仅是关闭窗口）
  • 重新打开Claude代码以加载新配置

建筑亮点

错误处理

服务器实现了一个复杂的错误分类系统 从不 除非绝对必要，否则令牌无效：

  • ✅ 从不清除令牌：500/502/503、429（速率限制）、网络错误、超时
  • ✅ 检索瞬态错误：403个错误（Spotify错误），网络故障
  • ✅ 仅在以下情况下清除令牌：刷新令牌返回 invalid_grant

许可证管理

  • 并发刷新重复数据消除：多个同时进行的API调用仅触发一个令牌刷新
  • 刷新令牌保存：如果未返回新的刷新令牌，则保留现有的刷新令牌（Spotify行为）
  • 5分钟过期缓冲：在令牌过期之前刷新令牌
  • 原子写入：将凭据写入临时文件，然后自动重命名

重试逻辑

  • 指数退避: 1s → 2s → 4s延迟（可配置）
  • 费率限制处理：尊重 Retry-After 标头
  • 智能重试：瞬态故障最多可尝试3次

发展

看 Developpent.md 用于本地测试、调试和发布工作流。

构建

npm run build

测试

npm test

棉绒

npm run lint

项目状态

当前版本：功能齐全的Spotify控件，具有全面的搜索和播放功能

✅ 已实现的功能：

  • 具有防弹错误处理和令牌管理的核心基础设施
  • 全面搜索（曲目、专辑、播放列表、播客）
  • 完全播放控制（播放、暂停、下一个、上一个、音量）
  • 高级播放功能（随机播放、重复模式、设备管理）
  • 具有传输功能的多设备支持
  • 实时回放状态监控

🚀 未来的增强功能：

  • 用户库管理（保存的曲目、专辑、播放列表）
  • 播放列表创建和编辑
  • 最近播放的曲目
  • 用户热门曲目和艺术家

许可证

麻省理工学院-见 许可证

作者

安德鲁·莱恩 andrew.rhyne@shopify.com

相关 MCP