内容
# spotify-mcp
一个适用于 Spotify 的远程 MCP 服务器，具有经纪的 OAuth 和服务器端智能层。将其作为自定义连接器添加到 Claude 中，一次登录到 Spotify，所有工具都可使用。无需本地安装，无需编辑 JSON，无需为每个用户创建 Spotify 开发者应用。
## 使用托管服务器
1. 在 Claude 中，前往设置，然后前往连接器，然后点击“添加自定义连接器”。
2. 粘贴以下网址：
```
https://spotify-mcp-u1c9.onrender.com/mcp
```
3. Claude 会打开一个 Spotify 登录页面，请批准它。
4. 要求 Claude 调用 `get_initial_context` 以确认连接。
您只需进行一次身份验证。服务器会在存储时加密您的 Spotify令牌，并透明地刷新它们。
注意：托管服务器后面的 Spotify 应用在开发模式下运行，Spotify 限制了 5 个授权用户。在您登录之前，您的 Spotify 帐户电子邮件必须由所有者添加到白名单中。如果您不在列表中，请改为自行托管。
## 自行托管
您需要：一个 [Spotify 开发者应用](https://developer.spotify.com/dashboard)，一个免费的 [Neon](https://neon.tech) Postgres 数据库，和一个免费的 [Render](https://render.com) 网络服务（Fly.io 或 Railway 也适用）。
1. **Spotify 仪表盘：** 创建一个应用。添加 `https://<您的主机>/callback` 作为重定向 URI。记下客户端 ID 和密钥。应用所有者需要活跃的 Premium 才能使用播放工具，每个用户的 Spotify 电子邮件必须在开发模式下在用户管理中添加（最多 5 个）。
2. **Neon：** 创建一个项目并复制连接字符串。
3. **Render：** 从此存储库创建一个网络服务。
- 构建命令：`npm ci --include=dev && npm run build && npm run db:migrate`（`--include=dev` 很重要：Render 设置 `NODE_ENV=production`，否则会跳过构建所需的开发依赖项；迁移针对每个部署的 `DATABASE_URL` 运行，并且是幂等的）
- 启动命令：`npm start`
- 健康检查路径：`/healthz`
4. **环境变量：** 在 Render 仪表盘中设置 `.env.example` 中的每个变量。存储库中没有敏感数据；服务器在启动时验证环境，如果缺少或格式不正确，则会退出并显示特定消息。 使用 `node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"` 生成 `MASTER_ENCRYPTION_KEY`，并为 `JWT_SIGNING_KEY` 使用一个长随机字符串。 `SPOTIFY_REDIRECT_URI` 必须与 Spotify 仪表盘中注册的重定向 URI 完全匹配，并且必须为 `<PUBLIC_BASE_URL>/callback`。如果 `MASTER_ENCRYPTION_KEY` 曾经更改，所有存储的令牌都将变得无法解密，每个用户都必须重新连接。
5. 验证 `https://<您的主机>/healthz` 返回 200 以及 `https://<您的主机>/.well-known/oauth-authorization-server` 返回元数据，然后从上面连接到 Claude。连接器 URL 为 `https://<您的主机>/mcp`；`/mcp` 路径是必需的。
## 开发
```
npm install
npm run dev # 使用本地 .env 进行 tsx 监视
npm test # 完整套件：单元测试 + 集成测试（针对内存 Postgres）
npm run typecheck
```
测试不需要网络或凭证。完整的系统设计、工具参考和决策日志位于 [`spotifymcp.md`](spotifymcp.md) 中。
