Yandex Music (unofficial)

yandex-music-mcp

Яндекс Музыки 向けの非公式 MCP サーバーです。Claude Desktop、Claude Code などの MCP クライアントに接続すると、アシスタントが「いいね」、再生履歴、「マイウェーブ」、プレイリストにアクセスできるようになります。

サーバーはお使いのコンピューター上でローカルに動作します（stdio）。トークンはお使いの環境にのみ保存され、外部に送信されることはありません。Windows、macOS、Linux に対応しています。

⚠️ 非公式プロジェクトです。 ООО «Яндекс» とは関係がなく、同社の承認も受けていません。非公式ライブラリ yandex-music を使用しているため、Яндекс が API を変更すると、サーバーが一時的に動作しなくなる場合があります。サーバーはオーディオをダウンロードしません。アカウントのメタデータ、「いいね」、プレイリストのみを扱います。

English version below ↓

---

できること

読み取り	変更
account_info — 接続の確認	create_playlist — 新しいプレイリスト（デフォルトでは非公開）
search — トラック、アルバム、アーティスト、プレイリストの検索	add_tracks_to_playlist — トラックの追加
get_liked_tracks — 「お気に入り」	remove_tracks_from_playlist — トラックの削除
get_listening_history — 日ごとの再生履歴	delete_playlist — プレイリストの削除（名前を確認）
list_my_playlists、get_playlist_tracks — 自分のプレイリスト	like_tracks / unlike_tracks — 「いいね」の追加・取り消し
get_playlist_by_url — リンクから任意の公開プレイリストまたはアルバムを取得	export_tracks_to_file — 「いいね」またはプレイリストを .txt と .csv に書き出し
get_album_tracks、get_artist_tracks — アルバムとアーティスト
get_similar_tracks、get_my_wave、get_chart — おすすめとチャート

サーバーは再生を操作しません。音楽は通常どおり Яндекс Музыки アプリで聴き、新しいプレイリストや「いいね」はすぐにアプリに反映されます。

リクエストの例

• 「最近『いいね』した300曲を分析して、聴いているジャンルや年代を教えて」
• 「今週聴いた曲は？」
• 「最近『いいね』した曲に似た25曲で、非公開プレイリスト「秋」を作って」
• 「友人のプレイリストはこちらです：<ссылка>。そこにある曲のうち、すでに『いいね』しているものはどれ？」
• 「『いいね』した曲をすべてファイルに書き出して」

---

クイックインストール

1. uv をインストールします — uv がコネクターをダウンロードして起動します。

• Windows（PowerShell）：

  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  

• macOS / Linux：

  curl -LsSf https://astral.sh/uv/install.sh | sh
  

ターミナルを閉じて開き直し、uv --version を実行して確認します。

2. Яндекс にログインします（初回のみ）。

uvx --from yandex-music-mcp yandex-music-mcp-auth

3. クライアントに接続します。

• Claude Code — コマンドを1つ実行します。

  claude mcp add yandex-music -- uvx yandex-music-mcp
  

• Claude Desktop — Settings → Developer → Edit Config を開き、claude_desktop_config.json に以下を追加します。

  {
    "mcpServers": {
      "yandex-music": {
        "command": "uvx",
        "args": ["yandex-music-mcp"]
      }
    }
  }
  

うまくいかない場合は、以下のソースからの詳細な手順に沿ってインストールしてください。

---

ソースからのインストール

uv と Яндекс アカウントが必要です。一部の機能（「マイウェーブ」など）では、Плюс サブスクリプションが必要になる場合があります。

1. uv をインストールします

Windows（PowerShell）：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS / Linux：

curl -LsSf https://astral.sh/uv/install.sh | sh

ターミナルを閉じて開き直し、uv --version を実行して確認します。

2. プロジェクトをダウンロードします

git clone https://github.com/kenzolika/yandex-music-mcp.git

または、リポジトリのページで Code → Download ZIP をクリックし、アーカイブを展開します。

3. トークンを取得します（初回のみ）

cd yandex-music-mcp
uv run yandex-music-mcp-auth

Яндекс のログインページ（ya.ru/device）が開き、ターミナルにコードが表示されます。アカウントにログインしてコードを入力し、ターミナルに「Готово!」と表示されるまで待ちます。トークンは ~/.yandex-music-mcp/token に保存されます。このスクリプトは Яндекс の公式ログインを使用し、パスワードを読み取ることはありません。

4. プロジェクトフォルダーのフルパスを確認する

クライアントがプロジェクトの場所を把握できるようにする必要があります。最も簡単なのは、プロジェクトフォルダーでターミナルを開いて確認する方法です（手順 3 の後なら、すでにそのフォルダーにいます）。

• Windows（PowerShell）： (Get-Location).Path → 例：C:\Users\Ivan\Documents\yandex-music-mcp
• macOS / Linux： pwd → 例：/Users/ivan/yandex-music-mcp

Windows ではマウスでも確認できます。エクスプローラーで Shift キーを押しながらフォルダーを右クリックし、**「パスのコピー」**を選択します。

Windows での注意： JSON 設定ファイルでは、バックスラッシュを二重にする必要があります：C:\\Users\\Ivan\\Documents\\yandex-music-mcp。代わりにスラッシュを使うこともできます。Windows はスラッシュも認識します：C:/Users/Ivan/Documents/yandex-music-mcp。

5а. Claude Desktop に接続する

Claude Desktop で Settings → Developer → Edit Config を開くと、claude_desktop_config.json ファイルが開きます。手順 4 で確認したパスを入れて、mcpServers ブロックを追加します。

{
  "mcpServers": {
    "yandex-music": {
      "command": "uv",
      "args": ["--directory", "C:/Users/Ivan/Documents/yandex-music-mcp", "run", "yandex-music-mcp"]
    }
  }
}

• ファイルにすでにほかの設定がある場合： 削除しないでください。"mcpServers": { ... } を最上位に追加し、ほかの設定との間にカンマを入れてください。
• Claude が uv を見つけられない場合： "command" に uv のフルパスを指定してください。パスは where.exe uv（Windows）または which uv（macOS/Linux）で確認できます。通常は C:/Users/Ivan/.local/bin/uv.exe または ~/.local/bin/uv です。

Claude Desktop を完全に終了して（Windows の場合はシステムトレイのアイコンから Quit を選択してください。ウィンドウの閉じるボタンだけでは不十分です）、もう一度起動します。

5б. または Claude Code に接続する

手順 5а の代わりに、手順 4 で確認したパスを使って次のコマンドを実行します。

claude mcp add yandex-music -- uv --directory "C:/Users/Ivan/Documents/yandex-music-mcp" run yandex-music-mcp

6. 動作を確認する

新しいチャットで「Yandex Music への接続を確認して」と入力します。返信に自分のログイン名が表示されれば、接続できています。

---

設定

変数	用途
YANDEX_MUSIC_TOKEN	トークンを直接指定します（ファイルの代わりに使用）
YANDEX_MUSIC_TOKEN_FILE	トークンを含むファイルへのパス
YANDEX_MUSIC_EXPORT_DIR	エクスポートデータの保存先（既定値は ドキュメント/Yandex Music exports）

セキュリティとプライバシー

• トークンを使うと、Music アカウントに完全にアクセスできます。公開したり、git に追加したりしないでください。.gitignore では、トークンファイルとエクスポートデータのファイルがすでに除外されています。
• id.yandex.ru のデバイスとサービスのセクションで、アクセスを取り消せます。
• 変更を行うすべてのツールには、MCP クライアント向けに変更を伴う操作であることがマークされています。Claude は既定で、これらの呼び出し前に確認を求めます。delete_playlist では、プレイリスト名を正確に指定する必要もあります。

トラブルシューティング

• Claude にサーバーが表示されない。 JSON に余分なカンマや不足しているカンマがないか、プロジェクトへのパスと uv へのパスが正しいか確認してください。ログ：%APPDATA%\Claude\logs\mcp-server-yandex-music.log（Windows）または ~/Library/Logs/Claude/（macOS）。
• 「トークンがありません」と表示される。 手順 3 をもう一度実行し、「完了！」と表示されるまでターミナルを閉じないでください。エラーメッセージには、サーバーがトークンを検索したパスが一覧表示されます。
• 更新後、新しいツールが表示されない。 Claude を再起動して、新しいチャットを開いてください。

---

英語

Yandex Music 用の非公式 MCP サーバーです。Claude Desktop、Claude Code、その他の MCP クライアントを Yandex Music ライブラリに接続します。対象は「いいね」、再生履歴、My Wave、プレイリストです。

サーバーはお使いのマシン上でローカルに実行されます（stdio）。トークンはお使いのコンピューターにのみ保存され、ほかの場所に送信されることはありません。Windows、macOS、Linux で動作します。

⚠️ 非公式プロジェクトです。 Yandex とは提携しておらず、Yandex の承認も受けていません。非公式の yandex-music ライブラリを使用しているため、Yandex が API を変更すると、一時的に動作しなくなる場合があります。このサーバーはオーディオをダウンロードしません。アカウント内のメタデータ、「いいね」、プレイリストのみを扱います。

ツール

読み取り	書き込み
account_info — 接続を確認します	create_playlist — 新しいプレイリスト（デフォルトは非公開）
search — トラック、アルバム、アーティスト、プレイリスト	add_tracks_to_playlist
get_liked_tracks — お気に入りのトラック	remove_tracks_from_playlist
get_listening_history — 日ごとの再生履歴	delete_playlist — プレイリストを削除します（正確なタイトルが必要です）
list_my_playlists、get_playlist_tracks — 自分のプレイリスト	like_tracks / unlike_tracks
get_playlist_by_url — リンクから公開プレイリストまたはアルバムを取得	export_tracks_to_file — お気に入りまたはプレイリストを .txt と .csv にエクスポートします
get_album_tracks、get_artist_tracks
get_similar_tracks、get_my_wave、get_chart — おすすめとチャート

このサーバーは再生を制御しません。通常どおり Yandex Music アプリで再生してください。新しいプレイリストやお気に入りはすぐにアプリに反映されます。

プロンプトの例：「お気に入りにした直近の300曲を分析して、よく聴くジャンルと年代を教えてください」 · 「今週は何を聴きましたか？」 · 「最近お気に入りにした曲に似たトラックを25曲集めた、非公開のプレイリスト『Autumn』を作成してください」 · 「友人のプレイリストはこちらです：。この中で、すでにお気に入りに入っている曲はどれですか？」 · 「お気に入りの曲をすべてファイルにエクスポートしてください」

クイックインストール

1. uvをインストールします。Windows（PowerShell）：powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"、macOS/Linux：curl -LsSf https://astral.sh/uv/install.sh | sh。ターミナルを開き直し、uv --versionを実行して確認します。
2. Yandex にサインインします（初回のみ）：uvx --from yandex-music-mcp yandex-music-mcp-auth
3. クライアントを接続します：
   • Claude Code： claude mcp add yandex-music -- uvx yandex-music-mcp
   • Claude Desktop： Settings → Developer → Edit Config を開き、claude_desktop_config.jsonに次を追加します：

     {
       "mcpServers": {
         "yandex-music": { "command": "uvx", "args": ["yandex-music-mcp"] }
       }
     }
     

ソースからインストール

1. uvをインストールします。 Windows（PowerShell）：powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"、macOS/Linux：curl -LsSf https://astral.sh/uv/install.sh | sh。ターミナルを開き直し、uv --versionを実行して確認します。
2. コードを取得します： git clone https://github.com/kenzolika/yandex-music-mcp.gitを実行するか、リポジトリのページでCode → Download ZIPを選択します。
3. トークンを取得します（初回のみ）： cd yandex-music-mcpを実行し、続けてuv run yandex-music-mcp-authを実行します。Yandex のサインインページ（ya.ru/device）が開き、ターミナルにコードが表示されます。サインインしてコードを入力し、「Готово!」（「完了！」）という行が表示されるまで待ちます。トークンは~/.yandex-music-mcp/tokenに保存されます。これは Yandex の公式 OAuth デバイスフローです。スクリプトがパスワードを見ることはありません。
4. プロジェクトフォルダーの絶対パスを確認します。 プロジェクトフォルダーで(Get-Location).Path（Windows PowerShell）またはpwd（macOS/Linux）を実行します。Windows では、エクスプローラーでフォルダーを Shift を押しながら右クリックし、Copy as pathを選択する方法もあります。JSON では、バックスラッシュを2つ重ねる（C:\\Users\\Ivan\\yandex-music-mcp）か、スラッシュ（C:/Users/Ivan/yandex-music-mcp）を使用してください。
5. クライアントを接続します。
   • Claude Desktop： Settings → Developer → Edit Config を選択すると、claude_desktop_config.jsonが開きます。次を追加します：

     {
       "mcpServers": {
         "yandex-music": {
           "command": "uv",
           "args": ["--directory", "/absolute/path/to/yandex-music-mcp", "run", "yandex-music-mcp"]
         }
       }
     }
     

     既存の設定はそのまま残し、コンマで区切って、その隣に"mcpServers"を追加してください。Claude がuvを見つけられない場合は、"command"にその絶対パスを指定します（Windows ではwhere.exe uv、macOS/Linux ではwhich uv）。その後、Claude Desktop を完全に終了し（Windows の場合：トレイアイコン → Quit）、再起動します。
   • Claude Code： claude mcp add yandex-music -- uv --directory /absolute/path/to/yandex-music-mcp run yandex-music-mcp
6. 確認します： 新しいチャットで「Yandex Music の接続を確認してください」と尋ねます。回答にログイン名が表示されれば、設定は完了です。

設定

変数	目的
YANDEX_MUSIC_TOKEN	ファイルの代わりにトークンを直接渡します
YANDEX_MUSIC_TOKEN_FILE	トークンファイルへのパス
YANDEX_MUSIC_EXPORT_DIR	エクスポートの保存先（デフォルト：Documents/Yandex Music exports）

セキュリティとプライバシー

• このトークンを使うと、Yandex Music アカウントに完全にアクセスできます。公開したり、コミットしたりしないでください。.gitignore では、トークンファイルとエクスポートはすでに除外されています。
• id.yandex.ru のデバイスとサービスからアクセスを取り消せます。
• 変更を行う各ツールには、MCP クライアント向けにその旨が示されるため、Claude は呼び出し前に確認を求めます。delete_playlist では、プレイリストの正確なタイトルも必要です。

トラブルシューティング

• Claude にサーバーが表示されません。 JSON に余分なカンマや不足しているカンマがないか、プロジェクトのパスと uv へのパスを確認してください。ログ：%APPDATA%\Claude\logs\mcp-server-yandex-music.log（Windows）または ~/Library/Logs/Claude/（macOS）。
• 「トークンがありません」というエラーが表示されます。 手順 3 をもう一度実行し、「完了！」と表示されるまでターミナルを開いたままにしてください。エラーメッセージには、サーバーがトークンを探したすべてのパスが表示されます。
• 更新後、新しいツールが表示されません。 Claude を再起動し、新しいチャットを開いてください。

---

作者 · 著者

Kenzolika & Claudiea 🎧 が、ある秋の夕べに人間とその AI パートナー（Claude）で作成しました。 Kenzolika & Claudiea が、ある秋の夕べに人間とその AI サイドキック（Claude）で作成しました。

ライセンス · ライセンス

MIT。LICENSE を参照してください。依存関係として、yandex-music（LGPL-3.0）ライブラリを変更せずに使用しています。 MIT。LICENSE を参照してください。yandex-music（LGPL-3.0）を変更せずに依存関係として使用しています。