使用说明

项目简介

本项目是一个基于Model Context Protocol (MCP) 构建的服务器，它集成 Spotify API，允许LLM客户端（如Claude）通过标准化的MCP协议与Spotify进行交互。用户可以通过LLM客户端指示服务器在Spotify上搜索音乐、创建和管理播放列表、获取音乐推荐等。

主要功能点

音乐搜索: 通过关键词在Spotify上搜索歌曲、艺术家和专辑。
播放列表管理: 创建、修改和浏览用户的Spotify播放列表。
音乐推荐: 基于用户喜好获取个性化的音乐推荐。
工具集成: 将Spotify API功能封装为可被LLM客户端调用的工具。
MCP协议支持: 实现了MCP协议，可以通过JSON-RPC与客户端通信。
Stdio传输协议: 使用标准输入输出 (Stdio) 作为服务器和客户端之间的通信通道。

安装步骤

克隆仓库:

git clone https://github.com/richbai90/spotify-mcp.git
cd spotify-mcp

配置Spotify API 凭据:
- 前往 Spotify Developer Dashboard 创建一个新的应用。
- 设置重定向 URI 为 'http://localhost:8888/callback'。
- 进入 'auth-app' 目录：'cd auth-app'
- 安装依赖：'npm install'
- 运行授权应用：'npm start'
- 按照浏览器中的指示完成Spotify授权，获取 refresh token。
- 返回项目根目录：'cd ..'

设置环境变量:

设置以下环境变量，将 placeholders 替换为您的 Spotify 应用凭据和 refresh token：

export SPOTIFY_CLIENT_ID="your-client-id"  # 替换为您的 Spotify Client ID
export SPOTIFY_CLIENT_SECRET="your-client-secret" # 替换为您的 Spotify Client Secret
export SPOTIFY_REFRESH_TOKEN="your-refresh-token" # 替换为您获取的 Spotify Refresh Token

注意: 确保环境变量设置正确，避免引号或多余空格，否则可能导致认证失败。

安装依赖并构建项目:

npm install
npm run build

运行服务器:

node dist/index.js

或者使用 Docker:

podman build -t mcp/spotify -f src/spotify/Dockerfile .
podman run -e SPOTIFY_CLIENT_ID="your-client-id" -e SPOTIFY_CLIENT_SECRET="your-client-secret" -e SPOTIFY_REFRESH_TOKEN="your-refresh-token" mcp/spotify

服务器配置

以下 JSON 配置信息用于 MCP 客户端配置连接 Spotify MCP 服务器。客户端需要配置 'mcpServers' 字段，其中 'spotify' 为自定义的服务名称。

{
  "mcpServers": {
    "spotify": {
      "command": "node",  // 运行服务器的命令，这里使用 node
      "args": [
        "dist/index.js"   // 服务器入口文件路径
      ],
      "serverTransport": "stdio" //  指定服务器传输协议为 stdio (标准输入输出)
    }
  }
}

使用 Docker 运行的配置示例:

{
  "mcpServers": {
    "spotify-docker": {  // 可以自定义服务名称，例如 spotify-docker
      "command": "podman", // 运行 Docker 容器的命令，这里使用 podman
      "args": [
        "run",          // podman run 命令
        "-i",           //  -i 参数保持STDIN开放，即使没有连接
        "--rm",         //  --rm 参数在容器退出后自动删除容器
        "-e",           //  -e 参数用于设置环境变量
        "SPOTIFY_CLIENT_ID=your-client-id", //  设置 Spotify Client ID 环境变量，需要替换为您的 Client ID
        "-e",           //  -e 参数用于设置环境变量
        "SPOTIFY_CLIENT_SECRET=your-client-secret", // 设置 Spotify Client Secret 环境变量，需要替换为您的 Client Secret
        "-e",           //  -e 参数用于设置环境变量
        "SPOTIFY_REFRESH_TOKEN=your-refresh-token", // 设置 Spotify Refresh Token 环境变量，需要替换为您获取的 Refresh Token
        "mcp/spotify"    // Docker 镜像名称，与构建时 '-t' 参数指定的名称一致
      ],
      "serverTransport": "stdio" //  指定服务器传输协议为 stdio (标准输入输出)
    }
  }
}

注意: 请将配置中的 'your-client-id', 'your-client-secret', 'your-refresh-token' 替换为实际的值。如果使用 Docker 部署，请确保 Docker 环境已正确安装和配置。

基本使用方法

确保 MCP 服务器已成功启动并运行。
在支持 MCP 协议的 LLM 客户端 (例如 Claude) 中配置上述服务器连接信息。
在 LLM 客户端中，您可以指示模型使用 Spotify 工具来执行以下操作：
- 搜索歌曲：例如，"在 Spotify 上搜索 Taylor Swift 的歌曲"
- 创建播放列表：例如，"创建一个名为 '放松音乐' 的播放列表"
- 添加歌曲到播放列表：例如，"将搜索到的歌曲添加到 '放松音乐' 播放列表"
- 获取音乐推荐：例如，"基于我听的爵士乐推荐一些歌曲"
- 查看我的播放列表：例如，"列出我的 Spotify 播放列表"
- 查看播放列表中的歌曲：例如，"查看 '放松音乐' 播放列表中的歌曲"
LLM 客户端会根据您的指令，自动调用 Spotify MCP 服务器提供的工具，并通过自然语言返回结果。

关键词