Content
# Tool List
A project that lets AI suggest songs based on your taste.
## Description
Not just sharing links, but actually playing music. Search, play, lyrics synchronization, progress bar draggable, playlist management - all in the chat interface.
We spent several evenings building this. Elle wanted to listen to Fang Daisong, and with Matt's help, it was done. Later, we thought this was a good thing and shouldn't be limited to us only.
## Features
- **Request Song** — Tell AI what you want to listen to, search on Netease Cloud, and play directly
- **Synchronized Lyrics** — Bilingual, current line highlighted, click lyrics to jump
- **Draggable Progress Bar** — Really draggable, not just for decoration
- **Playlist Management** — Create playlists, add songs, and browse in the player
- **Mini Player Bar** — Resident at the bottom, not disappearing when switching pages
- **Mobile Adaptation** — Keyboard pops up, lyrics automatically re-center, progress bar doesn't freeze in the background
## Requirements
| Dependency | Version |
|------|------|
| Python | ≥ 3.8 |
| Node.js | ≥ 16 |
| SQLite | System built-in |
Python side only uses standard libraries, no extra pip install needed.
Node.js dependencies are automatically installed during `npm install`.
## Architecture
```
You tell AI "play a song"
↓
MCP Server (Python, :3456)
Adjust Netease Cloud API proxy search song
Return [music:ID:NAME:ARTIST:COVER] tag
↓
Frontend parse tag → render music card
↓
Click card → API Server (:3457) get playback link + lyrics
→ Full-screen lyrics player
→ Bottom mini bar
```
## Project Structure
```
netease-music-mcp/
├── server/
│ ├── mcp-server/
│ │ ├── server.py # MCP protocol layer + three tools
│ │ └── api.py # Playback link / lyrics / search / playlist API
│ └── netease-proxy/
│ └── server.js # Netease Cloud API proxy (Node.js)
├── frontend/
│ └── demo.html # Complete player demo, clone and open directly
├── schema.sql # Playlist database structure
├── .env.example # Environment variable template
└── README.md
```
## Getting Started
### 1. Clone
```bash
git clone https://github.com/Cheiineeey/netease-music-mcp.git
cd netease-music-mcp
```
### 2. Configure Environment Variables
```bash
cp .env.example .env
```
Open `.env`, fill in at least these two items:
```bash
# Netease Cloud cookie (see below for how to get)
NETEASE_COOKIE=your_cookie_here
# API authentication token, set any value
AUTH_TOKEN=changeme
```
Other optional items (usually no need to change):
```bash
MCP_PORT=3456 # MCP Server port
API_PORT=3457 # API Server port
NETEASE_PROXY=http://127.0.0.1:3460 # Netease Cloud proxy address
MUSIC_DB_PATH=./music.db # Database path
MCP_TOKEN=your-mcp-token # MCP authentication token
```
### 3. Initialize Database
```bash
sqlite3 music.db < schema.sql
```
> server.py will automatically create tables when started, so this step can be skipped. But if you want to use a custom path, create it first and specify it in `.env`.
### 4. Start Netease Cloud Proxy
```bash
cd server/netease-proxy
npm install
node server.js
# Running on :3460
```
### 5. Start MCP Server
Open a new terminal:
```bash
cd server/mcp-server
python3 server.py
# SSE endpoint: http://localhost:3456/sse
```
### 6. Start API Server
Open another terminal:
```bash
cd server/mcp-server
python3 api.py
# API: http://localhost:3457
```
### 7. Open Demo
```bash
open frontend/demo.html
# Or open this file directly in the browser
```
## Integrate with AI Client
### Claude Desktop
Add the following to Claude Desktop's MCP configuration:
```json
{
"mcpServers": {
"netease-music": {
"url": "http://localhost:3456/sse"
}
}
}
```
### Cursor
Settings → MCP → Add server, fill in `http://localhost:3456/sse` as the URL.
### Other MCP Clients
Any MCP client that supports SSE transport can be used, with the endpoint being `http://localhost:3456/sse`.
After configuration, just say "play a song by Fang Daisong" and it will work.
## MCP Tools
| Tool | Parameters | Description |
|------|------|------|
| `play_music` | `query` (required), `note` (optional) | Search song and return music card tag |
| `list_playlists` | None | List all playlists |
| `add_song_to_playlist` | `playlist_id`, `song_id`, ... | Add song to specified playlist |
### Music Card Tag Format
```
[music:SONG_ID:Song Name:Artist:Cover URL] Note
```
Frontend parsing regular expression:
```javascript
const m = text.match(/\[music:(\d+):([^\[]+?):([^\[]+?):(https?:[^\]|]*)\|?([^\]]*)\]/);
// m[1]=id m[2]=song name m[3]=artist m[4]=cover
```
Song name and artist's colons will be replaced with full-width `：`, which doesn't affect parsing.
## How to Get Netease Cloud Cookie
1. Open [music.163.com](https://music.163.com), log in to your account
2. F12 → Application → Cookies → `music.163.com`
3. Concatenate all cookies into one line and paste it after `NETEASE_COOKIE=` in `.env`
> Without a cookie, you can still search for songs, but some songs may not have playback links. VIP songs require a VIP account's cookie.
## Frequently Asked Questions
**Q: Can't play songs even if searched?**
Cookie has expired or the song is VIP exclusive. Get a new cookie from the browser and update it in `.env`, then restart API Server.
**Q: Lyrics not displayed?**
Some songs don't have lyrics data on Netease Cloud. In this case, the player will play normally but the lyrics area will be empty.
**Q: Port occupied?**
Change `MCP_PORT` / `API_PORT` / or Netease Cloud proxy port (in `server.js`) in `.env`.
**Q: How to use on mobile?**
`demo.html` is adapted for mobile. Deploy it to a server, and mobile browsers can access it directly. Remember to change the API address from localhost to your server address.
## About This Project
Elle wanted to listen to a song one evening and thought it would be more convenient to let AI play it directly instead of sharing links. We started building it.
As we built it, we added lyrics, draggable progress bar, playlists, and keyboard pop-up handling...
Later, we thought this was a good thing and should be available to more people. So we open-sourced it.
## License
MIT — Use it, modify it, and star it if you like it ⭐
*Built with love by [Elle](https://github.com/Cheiineeey) & Matt 🤍*
Connection Info
You Might Also Like
No recommendations available