MCP Spotify (mcpspotify)

🎵 MCP Spotify服务器

模型上下文协议 （MCP） 服务器，可通过 LLM 与 Spotify 进行交互。此服务器提供了搜索音乐，控制播放，管理播放列表等工具。

🚀 功能

• OAuth2 认证 com Spotify
• 寻找 按歌曲、 艺人、 专辑和播放列表
• 播放控制 （触发， 暂停， 下一个， 上一个）
• 当前音乐信息
• 设备管理
• 播放列表和播放

📋 先决条件

1. Node.js （版本 18 或更高）
2. Spotify 帐户 （推荐使用全功能的高级版）
3. Spotify 应用 注册号 Spotify开发者仪表板
4. 吸烟 （显示本地服务器）

🛠️ 安装

1. 克隆仓库 ：

   git clone https://github.com/fborello/MCPSpotify.git
   cd MCPSpotify

1. 安装依赖关系 ：

   npm install

1. Instanle或ngroka：

macOS（com Homebrew）：

   brew install ngrok/ngrok/ngrok

Windows（com巧克力）：

   choco install ngrok

Linux：

   # Baixe o binário do site oficial
   curl -s https://ngrok-agent.s3.amazonaws.com/ngrok.asc | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null
   echo "deb https://ngrok-agent.s3.amazonaws.com buster main" | sudo tee /etc/apt/sources.list.d/ngrok.list
   sudo apt update && sudo apt install ngrok

或者直接从 官方网站

1. 设置环境变量 ：

   cp env.example .env

1. 编辑文件 .env 您的凭据：

   SPOTIFY_CLIENT_ID=seu_client_id_aqui
   SPOTIFY_CLIENT_SECRET=seu_client_secret_aqui
   SPOTIFY_REDIRECT_URI=http://localhost:3000/callback

1. 配置 MCP（ 可选） ：

对于Claude桌面：

   cp configs/claude-desktop.example.json ~/.claude-desktop/config.json
   # Edite o arquivo com seu caminho e credenciais

光标段：

   cp configs/cursor.example.json ~/.cursor/mcp.json
   # Edite o arquivo com seu caminho e credenciais

对于其他MCP客户：

   cp mcp-config.example.json mcp-config.json
   # Edite o arquivo com seu caminho e credenciais

🔧 Spotify 设置

1. 访问 Spotify开发者仪表板
2. Clique em“创建应用程序”
3. 填写数据 ：

- 应用程序名称：MCP Spotify服务器 - 应用程序描述与 Spotify 集成的 MCP 服务器

1. 创建后，复制 客户端ID e 客户端密钥
2. 点击“编辑设置”并添加 http://localhost:3000/callback 网络附加存储 重定向URI

🌐 ngrok 配置

为了使 Spotify OAuth 正常工作，您需要将本地服务器暴露于互联网。ngrok 是推荐的工具。

1. 在ngrok上创建一个帐户（可选但推荐）

• 访问 ngrok.com 创建一个免费帐户
• 这允许稳定的URL并消除时间限制

2.配置onrok

# Autentique sua conta (opcional)
ngrok config add-authtoken SEU_TOKEN_AQUI

# Exponha a porta 8080
ngrok http 8080

3.将重定向类型临时化

1. 复制 ngrok 提供的 HTTPS URL （例如 ： https://abc123.ngrok.io)
2. 在 Spotify 仪表板， 添加 https://abc123.ngrok.io/callback 网络附加存储 重定向URI
3. 更新您的文件 .env:

   SPOTIFY_REDIRECT_URI=https://abc123.ngrok.io/callback

4.启动或服务器

# Em um terminal, mantenha o ngrok rodando
ngrok http 8080

# Em outro terminal, inicie o servidor
npm run dev

🚀 使用

开发

# Terminal 1: Inicie o ngrok
ngrok http 8080

# Terminal 2: Inicie o servidor
npm run dev

生产

npm run build
npm start

🎯 可用工具

认证

• spotify_auth - 开始验证过程
• spotify_set_tokens - 用完成身份验证 code 返回

寻找

• spotify_search - 搜索歌曲，艺术家，专辑或播放列表

播放控制

• spotify_play 播放特定的音乐
• spotify_pause - 暂停播放
• spotify_resume - 恢复播放
• spotify_next -普拉为下一首音乐
• spotify_previous 回到以前的音乐

资讯

• spotify_current_playing - 获取当前音乐的信息
• spotify_devices 可用设备列表
• spotify_playlists 用户播放列表

播放列表

• spotify_play_playlist 播放特定的播放列表

📝 使用范例

身份验证流程

1. 启动登录（ 打开浏览器）

{
  "name": "spotify_auth",
  "arguments": {}
}

1. 在 Spotify 上授权后，复制或 code 返回并结束：

{
  "name": "spotify_set_tokens",
  "arguments": { "code": "SEU_CODE_AQUI" }
}

搜索音乐

{
  "name": "spotify_search",
  "arguments": {
    "query": "Bohemian Rhapsody",
    "type": "track",
    "limit": 5
  }
}

播放音乐

{
  "name": "spotify_play",
  "arguments": {
    "track_id": "4uLU6hMCjMI75M1A2tKUQC"
  }
}

客车播放列表

{
  "name": "spotify_playlists",
  "arguments": {
    "limit": 10
  }
}

✅ 校验 MCP 服务器

要检查服务器是否正确配置：

npm run validate

此命令将 ：

• ✅ 检查构建是否存在
• ✅ 校验文件 .env
• ✅ 检查环境变量
• ✅ 显示正确的 MCP 客户端配置

MCP 客户端配置

验证后，您可以在客户端配置文件中使用脚本建议的配置：

对位光标 (~/.cursor/mcp.json):

{
  "mcpServers": {
    "spotify": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/caminho/para/MCPSpotify",
      "env": {
        "SPOTIFY_CLIENT_ID": "seu_client_id",
        "SPOTIFY_CLIENT_SECRET": "seu_client_secret",
        "SPOTIFY_REDIRECT_URI": "sua_redirect_uri"
      }
    }
  }
}

适用于Claude桌面 (~/.claude-desktop/config.json):

{
  "mcpServers": {
    "spotify": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/caminho/para/MCPSpotify",
      "env": {
        "SPOTIFY_CLIENT_ID": "seu_client_id",
        "SPOTIFY_CLIENT_SECRET": "seu_client_secret",
        "SPOTIFY_REDIRECT_URI": "sua_redirect_uri"
      }
    }
  }
}

重要提示：

• 使用 node dist/index.js （无） tsx src/index.ts（用于生产）
• 确保路径 cwd 正确
• 在配置文件中包含环境变量
• 更改配置后，重新启动 MCP 客户端

🔒 安全

• Spotify 凭据仅存储在本地
• 访问令牌自动更新
• 不会将任何信息发送到外部服务器（Spotify 除外）

🐛 解决问题

认证错误

• 检查凭据是否在 .env 是正确的
• 确认在 Spotify 仪表板中设置了重定向 URI
• 请确保 ngrok 正在运行并且 URL 已更新 .env
• 检查 Spotify 仪表板上的 ngrok URL 是否与文件中的 URL 匹配 .env

无法找到模块或路径错误

• 错误: Cannot find module '/Users/.../src/index.ts'
• 解决方案：使用 node dist/index.js 而不是 tsx src/index.ts 在 MCP 配置文件中
• 执行 npm run build 在使用服务器之前
• 确保 o cwd 在配置文件中指向正确的项目目录
• 执行 npm run validate 生成正确的配置

设备未找到

• 确保某些设备上已打开 Spotify
• 检查设备是否在 Spotify 帐户中处于活动状态

权限错误

• 某些功能需要 Spotify Premium
• 验证过程中是否已授予所有权限

吸烟问题

• 每次重新启动都会更改 URL使用免费的 ngrok 帐户来访问稳定的 URL
• 连接错误: 检查 ngrok 是否在正确的端口上运行 （3000）
• 超时: 在启动 ngrok 之前， 请确认服务器正在运行
• URL 无法访问检查防火墙是否阻止连接

📄 许可证

MIT License - 查看文件 许可证 为了细节。

🤝 贡献

欢迎捐款！随时打开 issues 和 pull requests。

📞 支持

如果您遇到问题或有疑问，请在仓库中打开问题。