# 网易云音乐 MCP Server（Zeabur 部署）

让 Claude.ai（官方 Connector）通过 MCP 协议操控网易云音乐：**一起听、搜歌、加歌、切歌、发私信、查歌单**。

## 架构

```
Claude.ai (Connector)
  ↓ HTTPS（Streamable HTTP，/mcp 端点）
ncm-mcp 服务（Python FastMCP，本仓库）        ← 公网域名
  ├── 读操作（搜索/歌单/私信/详情）→ ncmapi 服务（NeteaseCloudMusicApi 镜像） ← 内网
  └── 写操作（一起听/切歌/加歌/发私信）→ eapi/weapi 加密 → interface.music.163.com
```

两个 Zeabur 服务：
| 服务 | 内容 | 是否公网 |
|------|------|----------|
| `ncmapi` | `binaryify/netease_cloud_music_api:latest` 镜像 | 否（内网） |
| `ncm-mcp` | 本仓库的 Python 服务 | 是（绑域名） |

> 为什么写操作不走镜像？Docker Hub 那个镜像太老，eapi 加密参数过期，一起听/发私信会 400。所以写操作在 Python 里直接加密直连官方接口。

## 前置

1. GitHub 仓库（本仓库）
2. 网易云音乐账号给 AI 用（「大号」），你自己的账号是「小号」，**互相关注**
3. 大号的完整 Cookie

## 获取 Cookie

1. 电脑浏览器打开 `music.163.com`，登录**大号**
2. `F12` → 网络(Network) → 随便找一个发到 `music.163.com` 的请求 → 请求标头 → 找到 `Cookie:` → **复制整条值**
3. ⚠️ **必须整条**，不能只抄 `MUSIC_U`（只存 MUSIC_U 的话写操作会全部 400）

## 部署步骤

### 1. 推代码到 GitHub

本仓库的 `master` 分支即为可部署代码，本地改完 `git push` 即可。

### 2. Zeabur 创建项目

登录 [zeabur.com](https://zeabur.com) → 新建一个 Project。

### 3. 部署 ncmapi 服务（镜像）

`Add Service` → `Docker Image` → 填镜像名：

```
binaryify/netease_cloud_music_api:latest
```

- 服务名改成 `ncmapi`
- **不用绑定域名**（内网给 ncm-mcp 调用）

### 4. 部署 ncm-mcp 服务（本仓库）

`Add Service` → `GitHub` → 选仓库 `Yvine34/ncm-mcp`

- Zeabur 会自动识别根目录的 `Dockerfile` 并构建
- 服务名改成 `ncm-mcp`

### 5. 配置环境变量

在 `ncm-mcp` 服务的 **Variables** 里加：

| 变量 | 值 | 说明 |
|------|-----|------|
| `COOKIE` | 大号的完整 Cookie | 必填，整条 |
| `NCM_API` | `http://ncmapi:3000` | ncmapi 的内网地址 |

> 如果 `http://ncmapi:3000` 连不通，就给 `ncmapi` 服务也绑个域名，然后 `NCM_API` 填那个公网 `https://域名`。

### 6. 绑定域名

`ncm-mcp` 服务 → `Domains` → 生成/绑定一个域名，得到 `https://xxx.zeabur.app`。

### 7. Claude.ai 添加 Connector

Claude.ai → `Settings` → `Connectors` → 添加：

- **URL**：`https://xxx.zeabur.app/mcp`
- **名称**：网易云音乐
- **权限**：Always allow

## 工具清单

| 工具 | 功能 | 加密 |
|------|------|------|
| `search_music` | 搜索音乐 | 走镜像 |
| `get_song_detail` | 歌曲详情 | 走镜像 |
| `get_user_playlist` | 用户歌单 | 走镜像 |
| `get_playlist_detail` | 歌单详情 | 走镜像 |
| `get_private_list` | 私信列表 | 走镜像 |
| `get_private_messages` | 私信历史 | 走镜像 |
| `get_login_status` | 登录状态 | 走镜像 |
| `get_user_detail` | 用户详情 | 走镜像 |
| `accept_listen_together` | 接受一起听 | eapi |
| `end_listen_together` | 退出一起听 | eapi |
| `listen_together_heartbeat` | 心跳保活（另有后台自动） | eapi |
| `listen_together_status` | 查询一起听状态 | eapi |
| `play_command` | 切歌（实时） | eapi |
| `add_song` | 加歌到播放列表 | eapi |
| `send_private_message` | 发私信 | weapi |
| `http_request` | 万能请求兜底 | 走镜像 |

## 使用流程

### 一起听

1. 你（小号）在网易云 APP 里给大号发一起听邀请
2. 告诉 Claude「私信给我发了一起听」
3. Claude 调 `get_private_list` / `get_private_messages` 读私信，解析出 `roomId`、`inviterId`
4. Claude 调 `accept_listen_together` 加入房间
5. 后台线程每 60s 自动心跳保活，房间不会过期

### 点歌

1. 告诉 Claude 想听什么
2. Claude 调 `search_music` 搜歌拿 `id`
3. Claude 调 `add_song` 加歌
4. 你清一次 APP 后台重进，同步列表
5. 之后 Claude 用 `play_command` 随时切歌，实时生效

### 发私信

Claude 调 `send_private_message` 直接发私信（weapi/RSA，这部分**未用真实 cookie 实测**，首次用需验证）。

## 常见问题

- **写操作全部 400**：Cookie 不完整，重新抓整条（含 `__csrf`、`MUSIC_U`、`MUSIC_A_T`、`MUSIC_R_T`）。
- **Connector 连不上**：确认 ncm-mcp 绑了域名，且 URL 是 `https://域名/mcp`（结尾带 `/mcp`）。
- **读操作报错**：确认 `NCM_API` 能通（ncmapi 服务在运行）。
- **一起听房间掉了**：正常，让 Claude 重新 `accept_listen_together`；自动心跳只在已 accept 的房间上生效。