Spotify Playlist Generator Mcp Server

Spotify 播放列表生成器 MCP 服务

一个模型上下文协议（MCP）服务，可让 AI 应用使用官方 Spotify Web API 搜索音乐曲目并管理播放列表。

功能

• 搜索音乐曲目：在 Spotify 上查找音乐曲目，并自定义搜索参数
• 获取曲目详情：检索特定曲目的详细信息
• 获取播放列表曲目：列出播放列表中的曲目
• 播放列表管理：全面管理播放列表，包括创建、编辑和管理播放列表（需要设置 OAuth）

设置

前置要求

• Node.js 18 或更高版本
• Spotify 开发者账户
• Spotify 应用凭据（Client ID 和 Client Secret）

安装

1. 克隆此仓库：

git clone https://github.com/danisss9/spotify-playlist-generator-mcp-server

2. 安装依赖项：

npm install

3. 创建 Spotify 应用：

   • 前往 Spotify 开发者控制台
   • 创建一个新应用
   • 记下 Client ID 和 Client Secret
   • 将 http://localhost:8888/callback 添加到重定向 URI 中

4. 设置环境变量：

# Create a .env file
echo "SPOTIFY_CLIENT_ID=your_client_id_here" > .env
echo "SPOTIFY_CLIENT_SECRET=your_client_secret_here" >> .env

5. 构建 TypeScript 代码：

npm run build

运行服务

开发时启用自动重新构建：

npm run dev

生产环境运行：

npm start

与 MCP 客户端配合使用

此服务使用 stdio 传输，因此可与任何支持 stdio 的 MCP 客户端配合使用。

Claude Desktop 配置

将以下内容添加到 Claude Desktop 配置文件：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "spotify-playlist-generator": {
      "command": "node",
      "args": ["/absolute/path/to/spotify-playlist-generator/build/index.js"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id_here",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret_here"
      }
    }
  }
}

Visual Studio Code 与 GitHub Copilot 配置

如要在 Visual Studio Code 中通过 GitHub Copilot 使用此 MCP 服务，需要在 VS Code 设置中进行配置：

1. 打开 VS Code 设置：按 Ctrl+,（Windows/Linux）或 Cmd+,（macOS）

2. 搜索 MCP：在搜索栏中输入“mcp”

3. 添加 MCP 服务配置：将以下内容添加到 VS Code 的 settings JSON 中：

{
  "github.copilot.chat.mcp.servers": {
    "spotify-playlist-generator": {
      "command": "node",
      "args": ["/absolute/path/to/spotify-playlist-generator/build/index.js"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id_here",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret_here"
      }
    }
  }
}

替代方法：使用设置界面

1. 前往 File > Preferences > Settings（或使用 Ctrl+,）
2. 搜索“GitHub Copilot MCP”
3. 点击“Github › Copilot › Chat: Mcp Servers”旁边的“Edit in settings.json”
4. 按照上方所示添加服务配置

设置环境变量

为确保安全，你也可以在系统范围内设置环境变量，而不是将其写入配置：

Windows（PowerShell）：

[Environment]::SetEnvironmentVariable("SPOTIFY_CLIENT_ID", "your_client_id_here", "User")
[Environment]::SetEnvironmentVariable("SPOTIFY_CLIENT_SECRET", "your_client_secret_here", "User")

Windows（命令提示符）：

setx SPOTIFY_CLIENT_ID "your_client_id_here"
setx SPOTIFY_CLIENT_SECRET "your_client_secret_here"

macOS/Linux：

export SPOTIFY_CLIENT_ID="your_client_id_here"
export SPOTIFY_CLIENT_SECRET="your_client_secret_here"
# Add to ~/.bashrc, ~/.zshrc, or ~/.profile to persist
echo 'export SPOTIFY_CLIENT_ID="your_client_id_here"' >> ~/.bashrc
echo 'export SPOTIFY_CLIENT_SECRET="your_client_secret_here"' >> ~/.bashrc

然后从 VS Code 配置中移除 env 部分：

{
  "github.copilot.chat.mcp.servers": {
    "spotify-playlist-generator": {
      "command": "node",
      "args": ["/absolute/path/to/spotify-playlist-generator/build/index.js"]
    }
  }
}

在 VS Code 中使用

配置完成后，你可以通过 GitHub Copilot Chat 使用 MCP 服务：

1. 打开 Copilot Chat（Ctrl+Alt+I 或点击聊天图标）
2. 使用自然语言与 Spotify 交互： -“搜索爵士乐曲” -“创建一个名为‘我的收藏’的新播放列表” -“将这些曲目添加到我的播放列表” -“向我展示这首 Spotify 曲目的详情”

可用工具

需要 OAuth 的工具（所有功能均需身份验证）

authenticate_spotify

通过 Spotify OAuth 进行身份验证，以启用音乐搜索和播放列表管理功能。

参数：

• getAuthUrl（布尔值，默认值：false）：设为 true 以获取授权 URL
• authCode（字符串，可选）：OAuth 流程返回的授权码

get_auth_status

检查当前的 Spotify 身份验证状态。

参数： 无

search_tracks

在 Spotify 上搜索音乐曲目。

参数：

• query（字符串）：曲目搜索词
• limit（数字，1-50，默认值：20）：结果数量上限
• market（字符串，可选）：用于筛选结果的 ISO 3166-1 alpha-2 国家代码

get_track_details

获取特定 Spotify 曲目的详细信息。

参数：

• trackId（字符串）：Spotify 曲目 ID
• market（字符串，可选）：市场对应的 ISO 3166-1 alpha-2 国家代码

create_playlist

创建新的 Spotify 播放列表（需要身份验证）。

参数：

• name（string）：播放列表名称
• description（string，可选）：播放列表描述
• public（boolean，默认值：false）：播放列表是否公开
• collaborative（boolean，默认值：false）：播放列表是否允许协作

edit_playlist

编辑现有播放列表信息（需要身份验证）。

参数：

• playlistId（string）：要编辑的播放列表 ID
• name（string，可选）：播放列表的新名称
• description（string，可选）：播放列表的新描述
• public（boolean，可选）：新的公开设置
• collaborative（boolean，可选）：新的协作设置

**注意：**必须至少提供一个字段（name、description、public 或 collaborative）才能更新。

add_to_playlist

向 Spotify 播放列表添加曲目（需要身份验证）。

参数：

• playlistId（string）：目标播放列表 ID
• trackUris（字符串数组）：要添加的 Spotify 曲目 URI 数组
• position（number，可选）：插入曲目的位置（从 0 开始的索引）

list_playlists

列出用户的 Spotify 播放列表（需要身份验证）。

参数：

• limit（number，1-50，默认值：20）：播放列表数量上限
• offset（number，最小值：0，默认值：0）：分页索引偏移量

get_playlist_tracks

获取 Spotify 播放列表中的曲目（需要身份验证）。

参数：

• playlistId（string）：要获取曲目的播放列表 ID
• limit（number，1-100，默认值：50）：返回的曲目数量上限
• offset（number，最小值：0，默认值：0）：分页索引偏移量

remove_from_playlist

从 Spotify 播放列表中移除曲目（需要身份验证）。

参数：

• playlistId（string）：要从中移除曲目的播放列表 ID
• trackUris（字符串数组）：要移除的 Spotify 曲目 URI 数组
• snapshotId（string，可选）：用于版本控制的播放列表快照 ID

OAuth 身份验证设置

要使用全部功能，需要设置 Spotify OAuth 2.0：

1. 设置 Spotify 开发者控制台

1. 前往 Spotify 开发者控制台
2. 使用 Spotify 账户登录
3. 点击“Create an App”
4. 填写应用名称和描述
5. 将 http://localhost:8888/callback 添加到重定向 URI
6. 复制 Client ID 和 Client Secret

2. 环境配置

将 OAuth 凭据添加到 .env 文件中：

SPOTIFY_CLIENT_ID=your_client_id_here
SPOTIFY_CLIENT_SECRET=your_client_secret_here

3. 身份验证流程

1. 使用 authenticate_spotify 工具并设置 getAuthUrl: true
2. 在浏览器中打开提供的 URL
3. 登录 Spotify 账户并授予权限
4. 从回调 URL 中复制授权码
5. 再次使用 authenticate_spotify 工具，并传入 authCode 参数

4. 使用已验证身份的功能

完成身份验证后，你可以：

• 搜索音乐曲目
• 获取曲目的详细信息
• 创建新的播放列表
• 编辑现有播放列表信息（名称、描述、隐私设置）
• 向播放列表添加曲目
• 列出播放列表
• 获取播放列表中的曲目
• 从播放列表中移除曲目

API 限制

• 速率限制：Spotify API 有速率限制（因端点而异）
• OAuth 令牌：访问令牌会在 1 小时后过期，需要刷新
• 市场限制：某些曲目可能在特定市场无法使用
• 权限：OAuth 作用域决定可用的操作

开发

构建

npm run build

开发模式

npm run dev

项目结构

src/
└── index.ts          # Main server implementation

build/                # Compiled JavaScript output

贡献

1. Fork 此仓库
2. 创建功能分支
3. 进行更改
4. 充分测试
5. 提交拉取请求

许可证

MIT 许可证——详情请参阅 LICENSE 文件

故障排除

常见问题

1. “SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET environment variables are required”

   • 确保已设置这两个环境变量
   • 验证 Spotify 应用中的凭据是否有效

2. “Authentication required” 错误

   • 先使用 authenticate_spotify 工具进行身份验证
   • 检查访问令牌是否已过期，并重新进行身份验证

3. “Rate limit exceeded” 错误

   • 等待速率限制重置
   • 降低 API 调用频率

4. 构建错误

   • 确保已安装 Node.js 18+
   • 运行 npm install，确保已安装所有依赖项
   • 使用 npm run build 检查 TypeScript 编译

5. “Track not available” 错误

   • 某些曲目可能在你所在的市场不可用
   • 尝试指定其他 market 参数

安全注意事项

• 切勿将 API 密钥提交到版本控制系统
• 使用环境变量配置敏感信息
• 验证所有用户输入
• 实施适当的错误处理和日志记录
• 注意遵守 Spotify 的 API 服务条款

---

此项目使用 GitHub Copilot 创建