netease-music-mcp

ローカルでの音楽再生を制御するためのMCPサーバーです。neteasecli とローカルの mpv を介して音楽を再生し、ローカルの歌詞プレイヤーWeb UIを提供します。

免責事項 / Disclaimer

本プロジェクトはNetEase Cloud Music（網易雲音楽）の公式MCPではなく、NetEase Cloud Musicと提携、関連、または承認されているものではありません。本プロジェクトは、個人の学習、研究、およびローカルでの自動化体験のみを目的としています。使用する際は、NetEase Cloud Musicおよび関連サービスの利用規約、著作権ルール、およびアカウント使用規定を遵守してください。

This project is not an official NetEase Cloud Music MCP and is not affiliated with, associated with, or endorsed by NetEase Cloud Music. It is intended for personal learning, research, and local automation experiments. Please use it responsibly and comply with the applicable NetEase Cloud Music terms of service, copyright rules, and account usage policies.

Claude DesktopのようなMCPクライアントを使用して、以下の操作が可能です：

• NetEase Cloud Musicの楽曲を検索して再生

• 一時停止、再開、停止、曲送り

• ローカルWebプレイヤーを開く：http://127.0.0.1:8765/

• 歌詞、プレイリスト、お気に入りの音楽、レコード再生ページの表示

• AIの回答前に、現在の楽曲、ジャンル、アーティスト、および現在の歌詞のコンテキストを読み取る

• 音楽鑑賞終了時に、ワンクリックで mpv を停止し、Webプレイヤーを閉じる

環境要件

本プロジェクトは現在、主にWindows向けです。

上流プロジェクト：wangwalk/neteasecli が必要です。コードはデフォルトで %APPDATA%\npm\node_modules からグローバルインストールされた neteasecli を検索します。

mpv は前提依存関係であり、事前にインストールし、PowerShellで直接 mpv --version が実行できることを確認してください。

neteasecli と mpv はシステム/グローバル依存関係であり、npm install では自動的にインストールされません。 neteasecli の現在のバージョンはNode.js 24以降を要求するため、プロジェクト全体をNode.js 24+で実行することを推奨します。 Windowsポータブル版の mpv.exe を使用している場合は、一時的にプロジェクトルートディレクトリに配置することも可能です。

インストール

プロジェクトをクローン：

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のWeb版にログインします。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 test：

npm run smoke

smoke は以下を確認します：

• システム PATH またはプロジェクトルートディレクトリで mpv が見つかるか

• neteasecli がグローバルにインストールされているか

MCPクライアント内でモデルに呼び出させることも可能です：

netease-music-mcp.check_environment

Claude Desktopの設定

Claude Desktopは claude_desktop_config.json を通じてローカルのMCPサーバーを登録します。設定完了後、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の設定ファイルを開く

WindowsでClaude Desktopの設定ファイルを開きます：

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 Cloud Musicにログインしていない場合は、以下を送信してください：

请调用 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を介さずにWeb UIを直接プレビューしたい場合：

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

その後、ブラウザで以下を開きます：

http://127.0.0.1:8765/

Webプレイヤーには以下が含まれます：

• お気に入りプレイリスト

• プレイリスト作成

• お気に入りの音楽

• 楽曲検索

• プレイリスト詳細ページ

• 下部プレイヤー

• 再生キュー

• レコード歌詞再生ページ

• 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 Cloud Musicの楽曲百科を優先）

• タイムスタンプ付き歌詞

• CLI提供時の翻訳歌詞

get_listening_context は以下のような ai_context を返します。歌詞は現在の再生時間以降の6行です：

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

注意：MCPサーバー自体は、Claudeが毎回回答する前に特定のツールを呼び出すことを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

コマンドが一時的に使用できない場合は、Nodeを使用してグローバルインストールされたCLIを直接実行することもできます：

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

NetEase Cloud Musicへのログイン方法

neteasecli はSMS認証コードログインではなく、ブラウザからNetEase Cloud MusicのCookieをインポートします：

1. ChromeまたはEdgeで https://music.163.com/ を開き、アカウントにログインします。

2. PowerShellに戻り、以下を実行：

neteasecli auth login

3. ログイン状態を確認：

neteasecli --pretty auth check

Claudeに直接呼び出させることも可能です：

netease-music-mcp.setup_netease_login

不足している手順を確認し、次に実行すべきコマンドを返します。

neteasecliがログインCookieを見つけられない

neteasecli auth login がブラウザ内のログインCookieを見つけられない場合は、neteasecli のセッションファイルを直接書き込むことができます。これはブラウザのロックファイルを処理するよりも直接的です。

デフォルトプロファイルのセッションファイルパスは：

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

ファイル内容には最低限 MUSIC_U が必要です：

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

MUSIC_U を取得する方法：

1. Edge、Chrome、またはその他のブラウザで https://music.163.com/ を開き、ログインします。

2. F12 を押して開発者ツールを開きます。

3. Application / アプリケーション タブに移動します。

4. 左側の Cookies -> https://music.163.com を探します。

5. MUSIC_U という名前のCookieを見つけ、その 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への誤アップロードを防ぎます。

Webページを閉じても音楽が再生され続ける

Webページはプレイヤーのインターフェースであり、実際に音声を再生しているのはバックグラウンドの mpv です。

再生のみ停止：

netease-music-mcp.stop

音楽鑑賞セッション全体を終了し、Webプレイヤーを閉じる：

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

Web UIを起動：

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

MCPサーバーを起動：

npm start