netease-music-mcp

MCP-сервер для управления локальным воспроизведением музыки. Он воспроизводит музыку через neteasecli и локальный mpv, а также предоставляет веб-интерфейс для отображения текстов песен.

免责声明 / Disclaimer

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

Данный проект не является официальным MCP-сервером NetEase Cloud Music и не связан, не аффилирован и не одобрен NetEase Cloud Music. Он предназначен исключительно для личного обучения, исследований и экспериментов с локальной автоматизацией. Пожалуйста, используйте его ответственно и соблюдайте условия обслуживания, правила авторского права и политики использования аккаунтов NetEase Cloud Music.

Вы можете попросить MCP-клиент, такой как Claude Desktop, помочь вам:

• Искать и воспроизводить песни из NetEase Cloud Music

• Ставить на паузу, возобновлять, останавливать и переключать треки

• Открывать локальный веб-плеер: http://127.0.0.1:8765/

• Отображать тексты песен, плейлисты, любимые треки и страницу воспроизведения в стиле виниловой пластинки

• Получать контекст о текущей песне, жанре, исполнителе и тексте песни перед ответом ИИ

• Остановить mpv и закрыть веб-плеер одной командой по завершении прослушивания

环境要求

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

Требуется вышестоящий проект: wangwalk/neteasecli. По умолчанию код ищет глобально установленный neteasecli в %APPDATA%\npm\node_modules.

mpv является обязательной зависимостью, которую необходимо установить заранее, убедившись, что команда mpv --version работает в PowerShell.

neteasecli и mpv являются системными/глобальными зависимостями и не устанавливаются автоматически через npm install. Текущая версия neteasecli требует Node.js 24 или новее, поэтому рекомендуется использовать Node.js 24+ для запуска всего проекта. Если вы используете портативную версию mpv.exe для Windows, вы можете временно разместить её в корневой папке проекта.

安装

Клонируйте проект:

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

Установите зависимости проекта:

npm install

Установите музыкальный CLI глобально:

npm install -g neteasecli

Сначала войдите в веб-версию NetEase Cloud Music в браузере. neteasecli выполняет вход путем импорта Cookie из браузера и не сохраняет ваш логин и пароль в MCP.

https://music.163.com/

Затем импортируйте статус входа в PowerShell:

neteasecli auth login

Если у вас несколько профилей Chrome/Edge, вы можете указать нужный профиль:

neteasecli auth login --profile "Profile 1"

Проверьте статус входа:

neteasecli --pretty auth check

Установите mpv. Выберите любой удобный для вас способ:

# Chocolatey
choco install mpv -y

# Scoop
scoop install mpv

Если PowerShell сообщает, что команда neteasecli не найдена, убедитесь, что каталог глобальных команд npm добавлен в PATH. В Windows это обычно %APPDATA%\npm.

检查安装

Проверка синтаксиса:

npm run check

Smoke-тест:

npm run smoke

smoke проверяет:

• Доступность mpv в системном PATH или корне проекта

• Глобальную установку neteasecli

Также можно вызвать проверку через модель в MCP-клиенте:

netease-music-mcp.check_environment

配置 Claude Desktop

Claude Desktop регистрирует локальные MCP-серверы через claude_desktop_config.json. После настройки Claude сможет видеть инструменты netease-music-mcp.

1. 确认项目绝对路径

Выполните в папке проекта:

pwd

Предположим, вывод:

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

Тогда путь к файлу MCP-сервера будет:

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

2. 打开 Claude Desktop 配置文件

Откройте файл конфигурации Claude Desktop в Windows:

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

Если путь не найден, сначала создайте каталог:

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

3. 写入 MCP 配置

Если файл пуст, вставьте следующее содержимое. Обязательно замените путь на свой собственный, используя двойные обратные слэши:

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

Если в файле уже есть другие MCP-серверы, добавьте только элемент "netease-music-mcp" в существующий список "mcpServers":

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

4. 重启并验证

После сохранения конфигурации полностью закройте и снова откройте Claude Desktop.

Затем отправьте в Claude:

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

Если в ответе neteaseCliInstalled, mpvAvailable и статус входа в норме, можно начинать заказывать музыку.

Если вы еще не вошли в NetEase, отправьте:

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

5. 常见配置错误

• В JSON пути Windows должны содержать двойные обратные слэши, например C:\\path\\to\\file.js

• args должны указывать на src\\server.js, а не на папку проекта

• После изменения конфигурации необходимо перезапустить Claude Desktop

• Если Claude не видит инструменты, сначала убедитесь, что node можно запустить напрямую в PowerShell:

node -v

单独启动 Web 播放器

Если вы хотите просмотреть веб-интерфейс без использования Claude:

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

Затем откройте в браузере:

http://127.0.0.1:8765/

Веб-плеер включает:

• Избранные плейлисты

• Создание плейлистов

• Мои любимые треки

• Поиск песен

• Страница сведений о плейлисте

• Плеер в нижней части экрана

• Очередь воспроизведения

• Страница с текстами песен в стиле винила

• Двуязычные тексты песен (если поддерживается CLI)

MCP 工具列表

推荐 Claude 指令

Рекомендуется добавить следующий текст в проектные или пользовательские инструкции 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。

使用示例

В Claude Desktop можно сказать:

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

听歌上下文是怎么工作的

После начала воспроизведения сервис кэширует информацию о текущей песне в .listening-state.json:

• ID песни

• Название

• Исполнитель

• Альбом

• URL обложки

• Длительность

• Жанр (приоритет из энциклопедии NetEase)

• Текст песни с временными метками

• Перевод текста (если предоставлен CLI)

get_listening_context возвращает ai_context, подобный приведенному ниже, где текст песни содержит 6 строк после текущего времени воспроизведения:

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

Примечание: Сам MCP-сервер не может на 100% заставить Claude вызывать инструмент перед каждым ответом. Рекомендуемая инструкция выше накладывает жесткое ограничение на вызов get_listening_context. Если вам нужна гарантия, вам потребуется создать прокси-слой или собственный клиент, который автоматически внедряет контекст прослушивания перед отправкой запроса модели.

常见问题

Claude 看不到工具

После изменения claude_desktop_config.json необходимо перезапустить Claude Desktop.

Также убедитесь, что src/server.js в конфигурации указывает на правильный абсолютный путь.

PowerShell 找不到 neteasecli

Сначала проверьте установку:

npm install -g neteasecli

Затем убедитесь, что каталог глобальных команд npm находится в PATH. В Windows обычно нужно включить:

%APPDATA%\npm

Если команда временно недоступна, можно запустить глобально установленный CLI напрямую через 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 не использует вход по SMS-коду, а импортирует Cookie из браузера:

1. Откройте https://music.163.com/ в Chrome или Edge и войдите в аккаунт.

2. Вернитесь в PowerShell и выполните:

neteasecli auth login

3. Проверьте статус входа:

neteasecli --pretty auth check

Вы также можете попросить Claude вызвать:

netease-music-mcp.setup_netease_login

Он проверит, какой шаг пропущен, и вернет команду для выполнения.

neteasecli 找不到登录 Cookies

Если neteasecli auth login не может найти Cookie в браузере, можно вручную записать файл сессии neteasecli. Это часто проще, чем разбираться с блокировками файлов браузера.

Путь к файлу сессии по умолчанию:

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

Минимальное содержимое файла должно содержать MUSIC_U:

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

Как получить MUSIC_U:

1. Откройте https://music.163.com/ в Edge, Chrome или другом браузере и войдите.

2. Нажмите F12 для открытия инструментов разработчика.

3. Перейдите в Application / Приложение.

4. Слева найдите Cookies -> https://music.163.com.

5. Найдите Cookie с именем MUSIC_U и скопируйте его Value.

Затем выполните в 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

Сначала убедитесь, что команда работает напрямую в PowerShell:

mpv --version

Если нет, установите mpv или добавьте папку с mpv.exe в системный PATH. Для локальной разработки можно поместить портативный mpv.exe в корень проекта; .gitignore уже игнорирует локальные бинарные файлы mpv и DLL, чтобы избежать их загрузки в GitHub.

关闭网页后音乐还在播放

Веб-страница — это только интерфейс плеера, аудио воспроизводит фоновый процесс mpv.

Только остановить воспроизведение:

netease-music-mcp.stop

Завершить сеанс и закрыть веб-плеер:

netease-music-mcp.shutdown

手动停止后台 mpv

Если вы хотите вручную остановить фоновый процесс воспроизведения, выполните в Windows PowerShell:

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

开发

Перейдите в папку проекта:

cd netease-music-mcp

Запустите проверку:

npm run check
npm run smoke

Запустите веб-интерфейс:

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

Запустите MCP-сервер:

npm start