# netease-music-mcp

一个**非官方**的 [Model Context Protocol](https://modelcontextprotocol.io)（MCP）服务，用于操作**网易云音乐**。它让任何兼容 MCP 的客户端（Claude、Cursor、VS Code 等各类智能体）通过统一的工具接口来搜索歌曲、创建与管理歌单、查看听歌记录、收藏歌曲以及获取每日推荐。

> ⚠️ 本项目与网易公司无任何隶属、背书或赞助关系。
> 它使用了未公开的网页接口，可能随时失效，请自行承担使用风险。
> **切勿将你的 `MUSIC_U` Cookie 分享给他人**——它等同于你的账号密码。

---

## 功能特性

- 🔍 **搜索歌曲**（`search_songs`、`play_music`）
- 📝 **歌单管理**——创建、列出、添加/移除歌曲、读取歌单内容
- 🕘 **听歌记录** 与 ❤️ **收藏/取消收藏** 歌曲
- 🎯 **每日推荐**（每日 30 首）
- 🔐 **三种登录方式**：
  - `set_cookie`——从浏览器开发者工具粘贴 Cookie（最可靠）
  - `login_netease`——打开真实浏览器，登录后自动抓取 Cookie（需 Playwright + Chrome/Edge）
  - `login_qr`——用网易云手机 App 扫描二维码登录（需 `pycryptodome` + `qrcode`）
- 🚀 **双传输模式**：`stdio`（默认，用于本地 MCP 客户端）与 `http`（Streamable HTTP + SSE）

---

## 安装

```bash
git clone https://github.com/your-org/netease-music-mcp.git
cd netease-music-mcp

python -m venv .venv
source .venv/bin/activate        # Windows 使用：.venv\Scripts\activate
pip install -e ".[all]"          # 安装 pycryptodome、qrcode、playwright
```

可选依赖（按需安装）：

| 额外依赖（extra） | 提供的功能                          |
|-------------------|-----------------------------------|
| `qr`              | `login_qr`（扫码登录）             |
| `browser`         | `login_netease`（浏览器登录）      |
| `all`             | 上述两者全部                       |

**基础服务**（搜索 + 歌单 + 听歌记录 + `set_cookie`）**无需任何第三方依赖**——仅依赖 Python 标准库。

---

## 配置

复制示例环境变量文件并填入你的 Cookie：

```bash
cp .env.example .env
```

编辑 `.env`：

```ini
# 依赖登录的工具必填
NETEASE_COOKIE=MUSIC_U=YOUR_MUSIC_U; __csrf=YOUR_CSRF

# 传输模式："stdio"（默认）或 "http"
MCP_MODE=stdio
MCP_HOST=127.0.0.1
MCP_PORT=3456
```

### 如何获取 Cookie

1. 在桌面浏览器中登录 <https://music.163.com>。
2. 打开开发者工具（`F12`）→ **Application（应用）** → **Cookies** → `music.163.com`。
3. 复制 `MUSIC_U` 与 `__csrf` 两个字段的值。
4. 按 `MUSIC_U=xxx; __csrf=yyy` 的格式填入 `NETEASE_COOKIE`。

> Cookie 也可在运行时通过 `set_cookie` 工具提供，或通过 `login_netease` / `login_qr` 自动抓取。

---

## 使用方式

### stdio（推荐用于本地 MCP 客户端）

直接运行：

```bash
python -m netease_music_mcp.server
# 或安装后使用：netease-music-mcp
```

在你的 MCP 客户端配置中加入（示例）：

```json
{
  "mcpServers": {
    "netease-music": {
      "command": "python",
      "args": ["-m", "netease_music_mcp.server"],
      "env": {
        "NETEASE_COOKIE": "MUSIC_U=xxx; __csrf=yyy"
      }
    }
  }
}
```

### http（Streamable HTTP + SSE）

```bash
MCP_MODE=http MCP_PORT=3456 python -m netease_music_mcp.server
```

随后将客户端指向 `http://127.0.0.1:3456/mcp`（或 `/sse`）。

---

## 可用工具（共 13 个）

| 工具                | 说明                                              |
|---------------------|--------------------------------------------------|
| `search_songs`      | 搜索歌曲，返回多个带 ID 的结果                     |
| `play_music`        | 搜索并返回第一条匹配歌曲（含封面与播放链接）        |
| `create_playlist`   | 创建新歌单                                        |
| `add_to_playlist`   | 向歌单添加歌曲（song_ids 为逗号分隔的字符串）      |
| `remove_from_playlist` | 从歌单移除歌曲                                |
| `list_my_playlists` | 列出当前用户的全部歌单                            |
| `get_playlist_songs`| 获取歌单中的歌曲（最多 50 首）                    |
| `get_play_history`  | 获取最近 / 累计的听歌记录                         |
| `like_song`         | 收藏或取消收藏歌曲                                |
| `daily_recommend`   | 获取当日 30 首每日推荐                            |
| `login_netease`     | 打开浏览器，登录后自动抓取 Cookie                 |
| `login_qr`          | 扫码登录（用网易云 App 扫码）                     |
| `set_cookie`        | 手动提供 `MUSIC_U=...; __csrf=...`               |

---

## 项目结构

```
netease-music-mcp/
├── README.md
├── LICENSE
├── pyproject.toml
├── requirements.txt
├── .env.example
├── .gitignore
└── src/
    └── netease_music_mcp/
        ├── __init__.py
        ├── server.py      # MCP 服务：工具定义、JSON-RPC、stdio + http 双传输
        └── crypto.py      # 网易 weapi 加密（AES-128-CBC + RSA 无填充）
```

---

## 注意事项与限制

- **登录相关接口**（`/weapi/`）需要使用网易非标准的加密方式
  （AES-128-CBC 两遍 + RSA **无** PKCS#1 填充），实现位于 `crypto.py`。
- 部分网络环境 / 数据中心 IP 会被网易风控，对 `/weapi/` 登录接口返回空响应。
  此时请改用 `set_cookie`，从你自己的浏览器（住宅 IP）获取 Cookie。
- 向歌单**批量添加**大量歌曲时，应**分批进行**（每次调用 ≤5 个 ID），
  以避免服务端静默截断请求。
- 本项目为非官方项目，请遵守网易的服务条款。

---

## 免责声明

本软件仅供学习和个人自动化用途。对于因使用本软件导致的任何账号问题、限流或违反服务条款的后果，作者不承担任何责任。网易云音乐是网易公司的商标。

---

## 开源协议

[MIT](./LICENSE)