AI导哈

Spotify API集成服务

一个提供与Spotify API无缝集成的MCP服务器，使AI助手能够控制和交互Spotify播放、管理播放列表、搜索音乐及获取用户收听数据。

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

使用说明

Spotify MCP服务器

模型上下文协议（MCP）服务器，提供与Spotify API的无缝集成，使人工智能助手能够控制Spotify播放并与之交互，管理播放列表，搜索音乐，以及检索用户收听数据。

目录

概述

Spotify MCP服务器弥合了人工智能助手和Spotify之间的差距，允许与您的音乐库和播放进行自然语言交互。无论您是想播放特定歌曲、创建播放列表、发现新音乐还是分析您的收听习惯，此服务器都提供了实现这一目标的工具。

特性

特点

  • 身份验证和授权：用于安全访问Spotify API的OAuth 2.0授权代码流
  • 播放控制：跨设备播放、暂停、跳过、调整音量和控制播放
  • 搜索：查找曲目、专辑、艺术家和播放列表
  • 图书馆管理：访问和管理已保存的曲目、专辑和播放列表
  • 用户数据：检索用户配置文件信息和收听统计信息

计划的功能

看 ROADMAP.md 了解详细的功能时间线和未来的增强功能。

快速开始

这 最快最简单 开始的方法是使用交互式安装向导：

# Run the setup wizard (no installation required!)
npx @darrenjaws/spotify-mcp setup

向导将：

  • ✅ 指导您创建Spotify Developer应用程序
  • ✅ 自动打开浏览器到正确的页面
  • ✅ 输入凭据时验证凭据
  • ✅ 为您的环境生成正确的配置
  • ✅ 为您提供Claude Desktop、Claude Code、Cursor、Windsurf、VS Code或OpenCode的复制粘贴就绪配置

就是这样！ 整个设置大约需要2分钟。

安装

选项1:NPM（推荐）

交互式设置（最简单）：

# No installation required - run the setup wizard
npx @darrenjaws/spotify-mcp setup

或者先全局安装：

npm install -g @darrenjaws/spotify-mcp

# Then run setup
spotify-mcp setup

使用npx而不使用安装向导：

# Skip to manual configuration (see Configuration section below)
npx -y @darrenjaws/spotify-mcp

选项2：来源

为了发展或贡献：

# Clone the repository
git clone https://github.com/darrenjaworski/spotify-mcp.git
cd spotify-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run the setup wizard
npm run build && node build/bin.js setup

配置

自动设置（推荐）

使用交互式设置向导获得最简单的配置体验：

npx @darrenjaws/spotify-mcp setup

向导将引导您完成以下操作：

  1. 创建Spotify开发者应用程序
  2. 获取您的客户ID和密码
  3. 选择你的人工智能工具（克劳德桌面、克劳德代码、光标、风帆、VS代码、OpenCode）
  4. 生成正确的配置文件

手动设置

如果您更喜欢手动配置或需要更新凭据：

Spotify应用程序设置

  1. 去 Spotify开发者仪表板
  2. 创建新应用程序
  3. 注意你的 客户端ID 和 客户端密钥
  4. 添加 http://127.0.0.1:3000/callback 到应用程序的重定向URI（注意：使用 127.0.0.1，不 localhost)

环境变量

对于NPM/npx用户：在Claude Desktop配置中配置环境变量（请参阅上面的MCP配置）。

从源头开发：创建一个 .env 项目根目录中的文件：

SPOTIFY_CLIENT_ID=your_client_id_here
SPOTIFY_CLIENT_SECRET=your_client_secret_here
SPOTIFY_REDIRECT_URI=http://127.0.0.1:3000/callback

MCP配置

克劳德桌面版

添加到您的Claude Desktop配置文件中：

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • 视窗: %APPDATA%/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "spotify": {
      "command": "npx",
      "args": ["-y", "@darrenjaws/spotify-mcp"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id_here",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret_here",
        "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:3000/callback"
      }
    }
  }
}

保存后重新启动Claude Desktop。

克劳德代码（CLI）

最简单的方法是 claude mcp add 命令：

claude mcp add spotify \
  -e SPOTIFY_CLIENT_ID=your_client_id_here \
  -e SPOTIFY_CLIENT_SECRET=your_client_secret_here \
  -e SPOTIFY_REDIRECT_URI=http://127.0.0.1:3000/callback \
  -- npx -y @darrenjaws/spotify-mcp

或手动添加到 ~/.claude.json （全球）或 .claude/settings.json （项目）：

{
  "mcpServers": {
    "spotify": {
      "command": "npx",
      "args": ["-y", "@darrenjaws/spotify-mcp"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id_here",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret_here",
        "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:3000/callback"
      }
    }
  }
}

证实 claude mcp list --你应该看看 spotify 在列表中。

光标

添加 .cursor/mcp.json 在您的项目中（或 ~/.cursor/mcp.json 全球）：

{
  "mcpServers": {
    "spotify": {
      "command": "npx",
      "args": ["-y", "@darrenjaws/spotify-mcp"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id_here",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret_here",
        "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:3000/callback"
      }
    }
  }
}

帆板运动

添加 ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "spotify": {
      "command": "npx",
      "args": ["-y", "@darrenjaws/spotify-mcp"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id_here",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret_here",
        "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:3000/callback"
      }
    }
  }
}

VS代码（GitHub副本）

添加 .vscode/mcp.json 在您的项目中（或全局的VS代码用户设置）：

{
  "servers": {
    "spotify": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@darrenjaws/spotify-mcp"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id_here",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret_here",
        "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:3000/callback"
      }
    }
  }
}

OpenCode

{
  "$schema": "https://opencode.ai/config.json",
  "spotify": {
    "command": ["npx", "-y", "@darrenjaws/spotify-mcp@latest"],
    "environment": {
      "SPOTIFY_CLIENT_ID": "your_client_id_here",
      "SPOTIFY_CLIENT_SECRET": "your_client_secret_here",
      "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:3000/callback"
    },
    "type": "local"
  }
}

来源（发展）

{
  "mcpServers": {
    "spotify": {
      "command": "node",
      "args": ["/absolute/path/to/spotify-mcp/build/bin.js"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id_here",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret_here",
        "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:3000/callback"
      }
    }
  }
}

备注：使用npx或全局安装时，必须在MCP配置中指定环境变量（而不是在 .env 文件）。

用法

配置后，您可以通过自然语言与Spotify进行交互：

  • “播放我的每周发现播放列表”
  • 播放迈克尔·杰克逊的专辑《颤栗》
  • “目前正在播放哪首歌？”
  • “用这些歌曲创建一个名为“健身混音”的播放列表…”
  • “跳到下一首曲目”
  • “打开随机播放”
  • “设置重复跟踪”
  • “向我展示上个月的顶尖艺术家”
  • “搜索披头士乐队的歌曲”
  • “将这首歌添加到我喜欢的歌曲中”

可用工具（共32个）

播放和设备控制（10个工具）

  • spotify_play -开始或恢复播放曲目、专辑、播放列表或艺术家
  • spotify_pause -暂停播放
  • spotify_next -跳到下一首曲目
  • spotify_previous -跳至上一曲目
  • spotify_set_volume -调整音量（0-100）
  • spotify_get_playback_state -获取当前播放信息（包括混洗/重复状态）
  • spotify_get_devices -列出可用的Spotify Connect设备
  • spotify_transfer_playback -将播放转移到其他设备
  • spotify_shuffle -启用或禁用随机播放模式
  • spotify_repeat -设置重复模式（跟踪、上下文或关闭）

搜索和发现（1个工具）

  • spotify_search -使用可选字段过滤器（艺术家、专辑、流派、年份、标签）搜索曲目、专辑、艺术家或播放列表

播放列表管理（8个工具）

  • spotify_get_playlists -获取用户的播放列表
  • spotify_get_playlist -获取特定播放列表详细信息
  • spotify_create_playlist -创建新的播放列表
  • spotify_add_to_playlist -将曲目添加到播放列表
  • spotify_remove_from_playlist -从播放列表中删除曲目
  • spotify_reorder_playlist_tracks -重新排序播放列表中的曲目
  • spotify_delete_playlist -删除（取消关注）播放列表
  • spotify_update_playlist -更新播放列表详细信息（名称、描述、公共/私人、协作）

图书馆管理（9个工具）

  • spotify_get_saved_tracks -获取保存在库中的曲目
  • spotify_get_saved_albums -将相册保存在您的库中
  • spotify_get_followed_artists -获取您关注的艺术家
  • spotify_save_tracks -将曲目保存到库中
  • spotify_remove_saved_tracks -从库中删除曲目
  • spotify_save_albums -将相册保存到您的库
  • spotify_remove_saved_albums -从库中删除相册
  • spotify_follow_artists -关注艺术家
  • spotify_unfollow_artists -取消关注艺术家

用户数据（3个工具）

  • spotify_get_user_profile -获取用户配置文件信息
  • spotify_get_top_items -获取用户的顶级艺术家或曲目
  • spotify_get_recently_played -获取最近播放的曲目

系统（1个工具）

  • spotify_open -打开Spotify桌面应用程序（支持macOS、Windows、Linux）

本地开发

先决条件

  • Node.js>=18.0.0
  • npm或纱线
  • 带有应用程序凭据的Spotify开发者帐户

初始设置

  1. 克隆并安装依赖项
git clone https://github.com/darrenjaworski/spotify-mcp.git
cd spotify-mcp
npm install
  1. 配置环境变量
cp .env.example .env
# Edit .env with your Spotify credentials
  1. 构建项目
npm run build

开发工作流程

观看模式（推荐）

在监视模式下运行TypeScript编译器进行自动重建：

npm run dev

这会持续监视文件更改并自动重建。在开发过程中，请在一个终端中保持此运行。

手动构建

npm run build       # Compile TypeScript to build/
npm run clean       # Remove build directory

测试您的MCP服务器

选项1:MCP检查员（推荐）

这 MCP检查员 是MCP服务器的官方交互式测试工具。它提供了一个基于浏览器的UI来测试工具、查看协议消息和调试服务器。

启动检查器：

npx @modelcontextprotocol/inspector node build/bin.js

这将在以下位置打开浏览器 http://localhost:6274 与：

  • 服务器连接窗格：配置传输和环境变量
  • 工具选项卡：查看所有可用工具并以交互方式进行测试
  • 资源选项卡：查看服务器资源
  • 通知窗格：查看实时协议消息

使用环境变量：

npx @modelcontextprotocol/inspector node build/bin.js -- \
  SPOTIFY_CLIENT_ID=your_id \
  SPOTIFY_CLIENT_SECRET=your_secret \
  SPOTIFY_REDIRECT_URI=http://127.0.0.1:3000/callback

启用调试日志记录：

DEBUG=true npx @modelcontextprotocol/inspector node build/bin.js

优点：

  • ✅ 交互式UI测试所有32个工具
  • ✅ 实时查看JSON-RPC消息
  • ✅ 开发过程中无需配置Claude Desktop
  • ✅ 快速迭代工具实现

选项2：使用Claude Desktop进行测试

添加到您的Claude Desktop配置中以进行真实世界的测试：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "spotify-dev": {
      "command": "node",
      "args": ["/absolute/path/to/spotify-mcp/build/bin.js"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret",
        "SPOTIFY_REDIRECT_URI": "http://127.0.0.1:3000/callback",
        "LOG_LEVEL": "debug"
      }
    }
  }
}

更改配置后重新启动Claude Desktop。

选项3：手动stdio测试

对于低级调试，您可以直接发送JSON-RPC消息：

# Build first
npm run build

# Test list tools
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node build/bin.js

# Test a tool call
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"spotify_get_user_profile","arguments":{}}}' | node build/bin.js

开发技巧

1.一起使用监视模式+检查器

1号航站楼：

npm run dev  # Watch mode - rebuilds on changes

2号航站楼：

npx @modelcontextprotocol/inspector node build/bin.js

每次重建后刷新检查器以测试更改。

2.启用调试日志记录

集 LOG_LEVEL=debug 在你的 .env 文件以查看详细日志：

LOG_LEVEL=debug node build/bin.js

3.测试单个工具

在与Claude集成之前，使用检查器的“工具”选项卡用不同的输入测试每个工具。

4.检查stderr中的日志

服务器登录到stderr（而不是stdout）以避免干扰stdio传输：

node build/bin.js 2> server.log  # Capture logs to file

测试

运行测试套件以验证工具注册和功能：

npm test              # Run all tests
npm run test:watch    # Run tests in watch mode

测试覆盖范围：

  • ✅ 16个测试文件中的310个测试
  • ✅ 用于播放、搜索、播放列表、库、用户和系统的工具级单元测试
  • ✅ 身份验证测试（凭据、令牌管理、文件权限、刷新、OAuth回调）
  • ✅ 记录器测试（敏感数据编辑、日志级别）
  • ✅ 错误处理测试（所有HTTP状态代码、安全性）
  • ✅ 服务器注册和集成测试
  • ✅ 客户端测试（令牌编排、重试逻辑、速率限制）
  • ✅ 验证测试（URI格式、数组大小、数值范围）
  • ✅ 安装向导和CLI参数测试

棉绒与编码质量

npm run lint           # Check code style
npm run lint:fix       # Auto-fix linting issues
npm run static-checks  # Run lint, build, and test together

故障排除

构建错误：

  • 确保已安装TypeScript： npm install
  • 检查节点版本： node --version （应大于等于18）

检查员未加载：

  • 检查端口6274是否可用
  • 尝试清除浏览器缓存
  • 重新启动检查器

OAuth错误：

  • 在中验证Spotify凭据 .env
  • 在Spotify仪表板中检查重定向URI匹配
  • 确保范围正确 src/spotify/auth.ts

服务器未响应：

  • 检查日志： LOG_LEVEL=debug node build/bin.js
  • 验证构建成功： ls -la build/
  • 使用简单的工具进行测试，例如 spotify_get_user_profile

认证流程

服务器使用Spotify的OAuth 2.0授权码流：

  1. 第一个请求触发身份验证流
  2. 用户被重定向到带有安全状态参数的Spotify登录，以进行CSRF保护
  3. 授权后，使用client_secret交换令牌
  4. 令牌安全地存储在 ~/.spotify-mcp/tokens.json 具有0600权限
  5. 令牌过期时会自动刷新

安全

  • OAuth令牌以受限文件权限（0600）安全存储，从不记录
  • 加密安全状态参数可防止CSRF攻击
  • 客户端机密保存在环境变量中，从不保存在源代码中
  • 所有API请求都使用HTTPS
  • 使用适用于机密服务器应用程序的授权码流

贡献

欢迎投稿！请在提交PR之前阅读我们的投稿指南。

  1. 分叉存储库
  2. 创建要素分支(git checkout -b feature/amazing-feature)
  3. 提交您的更改(git commit -m 'Add amazing feature')
  4. 推到分支(git push origin feature/amazing-feature)
  5. 打开拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件

致谢

支持

相关项目

资源

MCP开发工具

Spotify API

相关 MCP