内容
<div align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset=".github/assets/banner-dark.svg">
<img alt="music-mcp — in-chat music player" src=".github/assets/banner-light.svg" width="100%">
</picture>
[](https://github.com/asashiki/music-mcp/actions/workflows/ci.yml)
[](LICENSE)
**中文** · [简体中文](README.zh-CN.md)
</div>
# music-mcp
一款 MCP 服务器，允许 AI 直接在聊天中插入一个**可播放的音乐播放器**，包括封面艺术、樱花风格的进度条、动画 EQ、同步歌词和播放列表队列。音频来自任何与 [Meting](https://github.com/metowolf/Meting) 兼容的 API（网易 / 腾讯 / 酷狗 / 酷我 / 百度）。
## 工作原理
1. **`search_song`** — AI 通过关键词搜索平台并获取真实的歌曲 ID（因此它不必自己生成）。
2. **`play_song`** — 渲染单个曲目的播放器小部件。
3. **`play_playlist`** — 队列整个平台的播放列表（上一曲 / 下一曲，点击跳转队列，自动播放下一曲）。
服务器通过自己的源代理所有媒体（`/stream/:server/:id`，`/cover/...`，`/lrc/...`）：
- 小部件 iframe 只需要**一个 CSP 源**（`PUBLIC_BASE_URL`），
- 平台 CDN 重定向链不能破坏小部件下的 `<audio>`，
- 转发 `Range` 头部，因此拖动进度条有效。
## 播放器功能
- Asashiki 樱花设计令牌，通过 `prefers-color-scheme` 实现浅色 / 深色模式，
- 带发光 fallback 的封面艺术，NOW PLAYING 倾斜徽章，5 条动画 EQ，
- 进度条具有签名 -12° 切割填充，点击可跳转，单线时间戳，
- **同步歌词**：获取并解析 LRC，突出显示当前行，
- 播放列表队列，当前曲目高亮显示，自动播放下一曲。
## 快速开始
```bash
npm install
npm run build
npm start # 流媒体 HTTP 服务器在 :3000 上启动（/mcp/music，/mcp 别名，/healthz）
```
烟雾测试：
```bash
curl -s -X POST localhost:3000/mcp -H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_song","arguments":{"keyword":"夜に駆ける"}}}'
```
## 远程部署（claude.ai / ChatGPT 网页）
1. `cp .env.example .env`，设置 `PUBLIC_BASE_URL`（公共 HTTPS 源）。
2. `docker compose up -d` 启动服务。
3. 反向代理 `https://your-domain/mcp/music` → 容器 `:3000`，**另外** `/stream/*`，`/cover/*`，`/lrc/*`（相同容器）。
4. 在 claude.ai 上添加自定义连接器，地址为 `https://your-domain/mcp/music`。如果设置了 `MCP_AUTH_PASSWORD`，连接器将使用 OAuth 动态客户端注册，并显示密码授权页面。
> 主机缓存 `ui://` 资源按 URI。在小部件更改后，在 `src/widget/music-widget-html.ts` 中增加版本号（`player-v1.html` → `v2` ...）。
## 配置
| 变量名 | 默认值 | 含义 |
|---|---|---|
| `PUBLIC_BASE_URL` | _（生产环境中必填）_ | 公共 HTTPS 源；写入小部件 CSP 和媒体 URL。 |
| `PORT` | `3000` | HTTP 端口。 |
| `MCP_HTTP_PATH` | `/mcp/music` | 流媒体 HTTP MCP 路线。 |
| `ALLOWED_ORIGINS` | `PUBLIC_BASE_URL` 源 | CORS 允许列表，以逗号分隔。 |
| `METING_API_BASE` | `https://api.qijieya.cn/meting/` | 任意 Meting 兼容端点。 |
| `DEFAULT_MUSIC_SERVER` | `netease` | AI 未指定平台时使用的平台。 |
| `MCP_AUTH_PASSWORD` | _（空）_ | 远程连接器的可选密码门禁。留空以禁用身份验证。 |
| `MCP_AUTH_SERVICE_NAME` | `music-mcp` | OAuth 密码页面的可选显示名称。 |
## OAuth 密码身份验证
设置 `MCP_AUTH_PASSWORD` 以启用远程连接器的最小 OAuth 授权码流程。服务器公开 OAuth 发现和动态客户端注册，因此支持自动注册的客户端可以在不手动配置客户端 ID 的情况下连接。在连接过程中，在授权页面上输入配置的密码。
## 注意事项和礼仪
- 按需从配置的 Meting API 流式传输曲目；不会在磁盘上存储任何内容。
- 可用性取决于上游平台（地区锁定，付费曲目）。小部件显示一个优雅的“加载失败”状态，而不是崩溃。
- 将 `METING_API_BASE` 指向您自己的 Meting 部署以提高可靠性。
## 开发
```bash
npm run dev # 带有热重载的 HTTP 服务器
npm run typecheck
npm run build # 服务器（tsup）+ 小部件（IIFE 内联到 ui:// 资源）
```
## 许可证
MIT
