netease-music-mcp

Un servidor MCP para controlar la reproducción de música local. Reproduce música a través de neteasecli y mpv local, y proporciona una interfaz web de reproductor de música con letras.

免责声明 / Disclaimer

本项目不是网易云音乐官方 MCP，也不隶属于、关联于或受网易云音乐官方认可。本项目仅用于个人学习、研究和本机自动化体验。使用时请合理遵守网易云音乐及相关服务的服务条款、版权规则和账号使用规范。

Este proyecto no es un MCP oficial de NetEase Cloud Music y no está afiliado, asociado ni respaldado por NetEase Cloud Music. Está destinado al aprendizaje personal, la investigación y experimentos de automatización local. Por favor, úselo de manera responsable y cumpla con los términos de servicio, las reglas de derechos de autor y las políticas de uso de cuenta aplicables de NetEase Cloud Music.

Puedes pedirle a clientes MCP como Claude Desktop que te ayuden a:

• Buscar y reproducir canciones de NetEase Cloud Music

• Pausar, reanudar, detener y cambiar de canción

• Abrir el reproductor web local: http://127.0.0.1:8765/

• Mostrar letras, listas de reproducción, música favorita y la página de reproducción de vinilo

• Leer el contexto de la canción actual, género, artista y letra antes de que la IA responda

• Detener mpv y cerrar el reproductor web con un solo clic al terminar de escuchar

环境要求

本项目目前主要面向 Windows 使用。

Requiere el proyecto upstream: wangwalk/neteasecli. El código busca por defecto neteasecli instalado globalmente en %APPDATA%\npm\node_modules.

mpv es una dependencia previa, debe instalarse con antelación y asegurarse de que mpv --version se pueda ejecutar directamente en PowerShell.

neteasecli y mpv son dependencias del sistema/globales y no serán instaladas automáticamente por npm install. La versión actual de neteasecli requiere Node.js 24 o superior, por lo que se recomienda usar Node.js 24+ para ejecutar todo el proyecto. Si utilizas la versión portátil de mpv.exe para Windows, también puedes colocarla temporalmente en el directorio raíz del proyecto.

安装

Clonar el proyecto:

git clone https://github.com/luuu-h/netease-music-mcp.git
cd netease-music-mcp

Instalar dependencias del proyecto:

npm install

Instalar la CLI de música globalmente:

npm install -g neteasecli

Primero inicia sesión en la versión web de NetEase Cloud Music en tu navegador. El método de inicio de sesión de neteasecli consiste en importar cookies desde el navegador, no guardará tu nombre de usuario ni contraseña en el MCP.

https://music.163.com/

Luego, importa el estado de inicio de sesión en PowerShell:

neteasecli auth login

Si tienes múltiples perfiles de navegador Chrome/Edge, puedes especificar el perfil:

neteasecli auth login --profile "Profile 1"

Confirmar el estado de inicio de sesión:

neteasecli --pretty auth check

Instalar mpv. Elige cualquiera de los métodos habituales:

# Chocolatey
choco install mpv -y

# Scoop
scoop install mpv

Si PowerShell indica que no encuentra el comando neteasecli, asegúrate de que el directorio de comandos globales de npm se haya añadido al PATH. En Windows, suele ser %APPDATA%\npm.

检查安装

Verificación de sintaxis:

npm run check

Prueba de humo (Smoke test):

npm run smoke

smoke comprobará:

• Si mpv se puede encontrar en el PATH del sistema o en el directorio raíz del proyecto

• Si neteasecli está instalado globalmente

También puedes pedirle al modelo que lo invoque en el cliente MCP:

netease-music-mcp.check_environment

配置 Claude Desktop

Claude Desktop registra el servidor MCP local a través de claude_desktop_config.json. Una vez configurado, Claude podrá ver herramientas como netease-music-mcp.

1. 确认项目绝对路径

Ejecuta en el directorio del proyecto:

pwd

Suponiendo que la salida es:

C:\Users\you\projects\netease-music-mcp

Entonces la ruta del archivo del servidor MCP es:

C:\Users\you\projects\netease-music-mcp\src\server.js

2. 打开 Claude Desktop 配置文件

Abre el archivo de configuración de Claude Desktop en Windows:

notepad "$env:APPDATA\Claude\claude_desktop_config.json"

Si indica que no encuentra la ruta, crea el directorio primero:

New-Item -ItemType Directory -Force "$env:APPDATA\Claude"
notepad "$env:APPDATA\Claude\claude_desktop_config.json"

3. 写入 MCP 配置

Si el archivo está vacío, pega el siguiente contenido. Asegúrate de cambiar la ruta por la tuya y usar doble barra invertida:

{
  "mcpServers": {
    "netease-music-mcp": {
      "command": "node",
      "args": [
        "C:\\path\\to\\netease-music-mcp\\src\\server.js"
      ]
    }
  }
}

Si el archivo ya contiene otros servidores MCP, solo añade la entrada "netease-music-mcp" dentro de los "mcpServers" existentes:

{
  "mcpServers": {
    "existing-server": {
      "command": "..."
    },
    "netease-music-mcp": {
      "command": "node",
      "args": [
        "C:\\path\\to\\netease-music-mcp\\src\\server.js"
      ]
    }
  }
}

4. 重启并验证

Después de guardar la configuración, cierra completamente y vuelve a abrir Claude Desktop.

Luego envía a Claude:

请调用 netease-music-mcp.check_environment 检查我的本机音乐环境

Si el resultado muestra que neteaseCliInstalled, mpvAvailable y el estado de inicio de sesión son correctos, puedes empezar a pedir canciones.

Si aún no has iniciado sesión en NetEase, puedes enviar:

请调用 netease-music-mcp.setup_netease_login 带我完成网易云登录

5. 常见配置错误

• Las rutas de Windows en JSON deben usar doble barra invertida, por ejemplo C:\\path\\to\\file.js

• args debe apuntar a src\\server.js, no a la carpeta del proyecto

• Debes reiniciar Claude Desktop después de modificar la configuración

• Si Claude no ve las herramientas, asegúrate primero de que node se pueda ejecutar directamente en PowerShell:

node -v

单独启动 Web 播放器

Si deseas previsualizar la interfaz web sin pasar por Claude:

node .\src\server.js --web-player --port 8765

Luego abre en tu navegador:

http://127.0.0.1:8765/

El reproductor web incluye:

• Listas de reproducción guardadas

• Crear listas de reproducción

• Mi música favorita

• Búsqueda de canciones

• Página de detalles de listas de reproducción

• Reproductor inferior

• Cola de reproducción

• Página de reproducción de letras de vinilo

• Letras bilingües cuando la CLI lo admite

MCP 工具列表

推荐 Claude 指令

Se recomienda añadir el siguiente fragmento a las instrucciones del proyecto o instrucciones personalizadas de Claude:

你可以使用 netease-music-mcp MCP 控制本机音乐。

当用户要配置、登录、安装、修复或检查 neteasecli 时，调用 netease-music-mcp.setup_netease_login，并按工具返回的 steps 带用户完成登录。用户执行完命令后，再调用一次 netease-music-mcp.setup_netease_login 或 netease-music-mcp.check_environment 验证。

当用户第一次要求播放音乐、点歌、听歌、打开播放器、查看歌词播放器，或当前对话还没有打开过播放器界面时，你必须先调用 netease-music-mcp.open_web_player，并把返回的 localhost URL 告诉用户。

当用户要求播放音乐时，调用 netease-music-mcp.play_song 或 netease-music-mcp.play_track。
当用户要求切歌时，调用 netease-music-mcp.next_song。
当用户要求暂停、继续、停止时，调用 netease-music-mcp.pause、netease-music-mcp.resume、netease-music-mcp.stop。

音乐播放期间，每次回复用户前，都必须先调用 netease-music-mcp.get_listening_context。
把返回的 ai_context 当作当前对话上下文使用。

点歌或切歌成功后，也要使用工具返回的 ai_context。
playback.style 字段已经优先来自网易云歌曲百科，可直接作为曲风/风格使用。

如果 netease-music-mcp.open_web_player 已经返回过 URL，不要重复打开，除非用户明确要求重新打开播放器。
如果用户问播放器在哪里，直接给出上次的 URL；如果不知道 URL，再调用 netease-music-mcp.open_web_player。

当用户说“结束听歌”、“不听了”、“关闭播放器”、“停止整个程序”，或任何表示要结束音乐/听歌会话的请求时，调用 netease-music-mcp.shutdown。这个工具只结束本次听歌和 Web 播放器，不会关闭 MCP 工具进程，因此之后仍然可以继续调用 netease-music-mcp。

使用示例

En Claude Desktop puedes decir:

一起听歌吧，听歌过程中每次回复我之前请先看 listening_context
打开音乐播放器
播放 布拉格广场 蔡依林
切到 编号89757 林俊杰
暂停
继续
结束听歌

听歌上下文是怎么工作的

Cada vez que comienza la reproducción, el servicio guarda en caché la información de la canción actual en .listening-state.json:

• ID de canción

• Nombre de la canción

• Artista

• Álbum

• URL de la portada

• Duración de la canción

• Género, preferiblemente de la enciclopedia de canciones de NetEase

• Letras con marca de tiempo

• Letras traducidas cuando la CLI las proporciona

get_listening_context devolverá un ai_context similar al siguiente, donde las letras son las 6 líneas posteriores al tiempo de reproducción actual:

我们正在一起听歌，你现在跟我一起听xxx，曲风是xxx，歌手是xxx，当前的6句歌词是xxx

Nota: El servidor MCP por sí mismo no puede forzar al 100% a Claude a llamar a una herramienta antes de cada respuesta. Las instrucciones recomendadas arriba obligarán a Claude a llamar proactivamente a get_listening_context. Si necesitas una garantía estricta, deberás crear una capa de proxy o un cliente personalizado que inyecte automáticamente el contexto de escucha antes de cada envío al modelo.

常见问题

Claude 看不到工具

Debes reiniciar Claude Desktop después de modificar claude_desktop_config.json.

También confirma que la ruta absoluta a src/server.js en la configuración sea correcta.

PowerShell 找不到 neteasecli

Primero confirma la instalación:

npm install -g neteasecli

Luego confirma que el directorio de comandos globales de npm esté en el PATH. En Windows, normalmente debe incluir:

%APPDATA%\npm

Si el comando no está disponible temporalmente, también puedes ejecutar la CLI instalada globalmente directamente con Node:

node "$env:APPDATA\npm\node_modules\neteasecli\dist\index.js" auth login
node "$env:APPDATA\npm\node_modules\neteasecli\dist\index.js" --pretty auth check

如何登录网易云

neteasecli no utiliza inicio de sesión por código SMS, sino que importa cookies de NetEase Cloud Music desde el navegador:

1. Abre https://music.163.com/ en Chrome o Edge e inicia sesión en tu cuenta.

2. Vuelve a PowerShell y ejecuta:

neteasecli auth login

3. Comprueba el estado de inicio de sesión:

neteasecli --pretty auth check

También puedes pedirle directamente a Claude que lo invoque:

netease-music-mcp.setup_netease_login

Comprobará qué paso falta y devolverá el comando que debes ejecutar a continuación.

neteasecli 找不到登录 Cookies

Si neteasecli auth login no encuentra las cookies de inicio de sesión en el navegador, puedes escribir manualmente el archivo de sesión de neteasecli. Esto suele ser más directo que intentar resolver problemas de bloqueo de archivos del navegador.

La ruta del archivo de sesión del perfil predeterminado es:

C:\Users\<你的用户名>\.config\neteasecli\profiles\default\session.json

El contenido del archivo solo necesita al menos MUSIC_U:

{"MUSIC_U":"这里填你从浏览器里拿到的值"}

Método para obtener MUSIC_U:

1. Abre https://music.163.com/ en Edge, Chrome u otro navegador e inicia sesión.

2. Presiona F12 para abrir las herramientas de desarrollador.

3. Ve a Application / Aplicación.

4. En el lado izquierdo, busca Cookies -> https://music.163.com.

5. Busca la cookie llamada MUSIC_U y copia su Value.

Luego ejecuta en PowerShell:

New-Item -ItemType Directory -Force "$HOME\.config\neteasecli\profiles\default"
Set-Content -Encoding UTF8 "$HOME\.config\neteasecli\profiles\default\session.json" '{"MUSIC_U":"把这里替换成你的MUSIC_U"}'
neteasecli --pretty auth check

Smoke test 提示找不到 mpv

Primero confirma que se puede ejecutar directamente en PowerShell:

mpv --version

Si no es así, instala mpv o añade el directorio donde se encuentra mpv.exe al PATH del sistema. Si solo estás desarrollando localmente, también puedes colocar la versión portátil de mpv.exe en la raíz del proyecto; el .gitignore del proyecto ya ignora los binarios y DLLs de mpv locales para evitar subirlos accidentalmente a GitHub.

关闭网页后音乐还在播放

La página web es solo la interfaz del reproductor; quien realmente reproduce el audio es el mpv en segundo plano.

Solo para detener la reproducción:

netease-music-mcp.stop

Para finalizar toda la sesión de escucha y cerrar el reproductor web:

netease-music-mcp.shutdown

手动停止后台 mpv

Si deseas detener manualmente el proceso de reproducción en segundo plano, puedes ejecutar en Windows PowerShell:

Get-Process mpv,mpv.com -ErrorAction SilentlyContinue | Stop-Process -Force

开发

Primero entra en el directorio del proyecto:

cd netease-music-mcp

Ejecuta la verificación:

npm run check
npm run smoke

Inicia la interfaz web:

node .\src\server.js --web-player --port 8765

Inicia el servidor MCP:

npm start