Content
# netease-music-mcp
A **non-official** [Model Context Protocol](https://modelcontextprotocol.io) (MCP) service for interacting with **Netease Music**. It allows any MCP-compatible client (such as Claude, Cursor, VS Code, etc.) to search for songs, create and manage playlists, view listening history, favorite songs, and get daily recommendations through a unified tool interface.
> ⚠️ This project has no affiliation, endorsement, or sponsorship from Netease.
> It uses undocumented web interfaces that may change at any time, so use at your own risk.
> **Do not share your `MUSIC_U` Cookie with others** - it is equivalent to your account password.
## Features
- 🔍 **Search Songs** (`search_songs`, `play_music`)
- 📝 **Playlist Management** - create, list, add/remove songs, read playlist contents
- 🕘 **Listening History** and ❤️ **Favorite/Unfavorite** songs
- 🎯 **Daily Recommendations** (30 songs per day)
- 🔐 **Three Login Methods**:
- `set_cookie` - paste Cookie from browser developer tools (most reliable)
- `login_netease` - open a real browser, log in, and automatically grab the Cookie (requires Playwright + Chrome/Edge)
- `login_qr` - scan QR code to log in (requires `pycryptodome` + `qrcode`)
- 🚀 **Dual Transmission Modes**: `stdio` (default, for local MCP clients) and `http` (Streamable HTTP + SSE)
## Installation
```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 uses: .venv\Scripts\activate
pip install -e ".[all]" # Install pycryptodome, qrcode, playwright
```
Optional dependencies (install as needed):
| Extra Dependency | Provided Functionality |
|-------------------|-----------------------------------|
| `qr` | `login_qr` (scan QR code to log in) |
| `browser` | `login_netease` (browser-based login) |
| `all` | all of the above |
**Basic Service** (search + playlist + listening history + `set_cookie`) **does not require any third-party dependencies** - only Python standard library.
## Configuration
Copy the example environment variable file and fill in your Cookie:
```bash
cp .env.example .env
```
Edit `.env`:
```ini
# Required for login tools
NETEASE_COOKIE=MUSIC_U=YOUR_MUSIC_U; __csrf=YOUR_CSRF
# Transmission mode: "stdio" (default) or "http"
MCP_MODE=stdio
MCP_HOST=127.0.0.1
MCP_PORT=3456
```
### How to Get Cookie
1. Log in to <https://music.163.com> on a desktop browser.
2. Open developer tools (`F12`) → **Application (Apps)** → **Cookies** → `music.163.com`.
3. Copy the values of `MUSIC_U` and `__csrf`.
4. Fill in `NETEASE_COOKIE` in the format `MUSIC_U=xxx; __csrf=yyy`.
> Cookie can also be provided at runtime through the `set_cookie` tool or automatically grabbed by `login_netease` / `login_qr`.
## Usage
### stdio (Recommended for Local MCP Clients)
Run directly:
```bash
python -m netease_music_mcp.server
# or use: netease-music-mcp (after installation)
```
Add to your MCP client configuration (example):
```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
```
Then point your client to `http://127.0.0.1:3456/mcp` (or `/sse`).
## Available Tools (13 in total)
| Tool | Description |
|---------------------|--------------------------------------------------|
| `search_songs` | Search for songs, return multiple results with IDs |
| `play_music` | Search and return the first matching song (with cover and playback link) |
| `create_playlist` | Create a new playlist |
| `add_to_playlist` | Add songs to a playlist (song_ids as comma-separated string) |
| `remove_from_playlist` | Remove songs from a playlist |
| `list_my_playlists` | List all playlists of the current user |
| `get_playlist_songs`| Get songs in a playlist (up to 50 songs) |
| `get_play_history` | Get recent or cumulative listening history |
| `like_song` | Favorite or unfavorite a song |
| `daily_recommend` | Get 30 daily recommendations |
| `login_netease` | Open a browser, log in, and automatically grab the Cookie |
| `login_qr` | Scan QR code to log in (using Netease Music App) |
| `set_cookie` | Manually provide `MUSIC_U=...; __csrf=...` |
## Project Structure
```
netease-music-mcp/
├── README.md
├── LICENSE
├── pyproject.toml
├── requirements.txt
├── .env.example
├── .gitignore
└── src/
└── netease_music_mcp/
├── __init__.py
├── server.py # MCP service: tool definitions, JSON-RPC, stdio + http dual transmission
└── crypto.py # Netease weapi encryption (AES-128-CBC + RSA without padding)
```
## Notes and Limitations
- **Login-related interfaces** (`/weapi/`) use Netease's non-standard encryption (AES-128-CBC twice + RSA **without** PKCS#1 padding), implemented in `crypto.py`.
- Some network environments/data centers may have IP restrictions on `/weapi/` login interfaces, returning empty responses. In this case, use `set_cookie` to get the Cookie from your own browser (residential IP).
- When **batch-adding** a large number of songs to a playlist, **split the requests** (≤5 IDs per call) to avoid server-side silent truncation.
- This project is non-official, so please comply with Netease's terms of service.
## Disclaimer
This software is for learning and personal automation purposes only. The author is not responsible for any account issues, rate limiting, or terms of service violations resulting from using this software. Netease Music is a trademark of Netease.
## License
[MIT](./LICENSE)
