yandex-music-mcp is an unofficial MCP (Model Context Protocol) server for connecting Claude Desktop, Claude Code, and other MCP clients to a user's Yandex Music account. It lets AI assistants access the user's music library, including likes, listening history, My Wave, and playlists.
Purpose The server's main purpose is to let AI assistants perform queries and operations based on the user's Yandex Music data. For example, analyzing the genre and era distribution of the last 300 likes, viewing this week's listening history, creating a private playlist with 25 similar tracks based on recent likes, checking which tracks in a playlist shared by a friend are already in the user's likes, and exporting all likes to a file.
Main capabilities The server provides access to: search, likes, listening history, My Wave, and playlists. It supports viewing public playlists by link, managing playlists, and exporting the music library to TXT/CSV format. All tools that modify data are marked as "modifying" in the MCP client, and Claude will request confirmation before calling them by default; delete_playlist also requires the exact name of the playlist.
Usage The server runs locally via stdio, and the token is stored only on the user's computer and is not sent anywhere else. It supports Windows, macOS, and Linux.
Quick installation:
- Install 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 Close the terminal and reopen it, then check: uv --version
- Log in to Yandex (once): uvx --from yandex-music-mcp yandex-music-mcp-auth
- Connect the client: Claude Code: claude mcp add yandex-music -- uvx yandex-music-mcp Claude Desktop: open Settings → Developer → Edit Config, and add to claude_desktop_config.json: { "mcpServers": { "yandex-music": { "command": "uvx", "args": ["yandex-music-mcp"] } } }
Installing from source:
- Install uv (same as above).
- Get the code: git clone https://github.com/kenzolika/yandex-music-mcp.git，或在仓库页面点击 Code → Download ZIP.
- Get the token (once): cd yandex-music-mcp, then uv run yandex-music-mcp-auth. The Yandex login page will open (ya.ru/device), and the terminal will display a code. Log in and enter the code, then wait for "Готово!" ("Done!") to appear. The token is saved to ~/.yandex-music-mcp/token. The script uses Yandex's official OAuth device flow and will not see the password.
- Get the full path to the project folder: in the project folder, run (Get-Location).Path (Windows PowerShell) or pwd (macOS/Linux). On Windows, you can also Shift + right-click the folder in File Explorer → Copy as path. In JSON, backslashes must be doubled (C:\Users\Ivan\yandex-music-mcp) or use forward slashes (C:/Users/Ivan/yandex-music-mcp).
- Connect the client: Claude Desktop: Settings → Developer → Edit Config to open claude_desktop_config.json, and add: { "mcpServers": { "yandex-music": { "command": "uv", "args": ["--directory", "/absolute/path/to/yandex-music-mcp", "run", "yandex-music-mcp"] } } } Keep the existing settings, and add "mcpServers" at the top level separated by commas. If Claude cannot find uv, enter its full path in "command" (use where.exe uv on Windows, which uv on macOS/Linux). Then fully quit Claude Desktop (Windows: tray icon → Quit) and restart it. Claude Code: claude mcp add yandex-music -- uv --directory /absolute/path/to/yandex-music-mcp run yandex-music-mcp
- Check: In a new chat, ask "Check my Yandex Music connection." If the response shows your login name, everything is working.
Use cases Suitable for users who want an AI assistant to analyze personal music listening habits, manage playlists, export liked data, or generate new playlists based on existing preferences. Requires uv and a Yandex account to be installed; some features (such as My Wave) may require a Plus subscription.
Limitations This project is unofficial and is not affiliated with or endorsed by Yandex. It is built on the unofficial yandex-music library; if Yandex changes the API, the server may temporarily stop working. The server does not download audio and only processes metadata, likes, and playlists in the account. The server does not control playback: music is still listened to normally in the Yandex Music app, and new playlists and likes appear there immediately. The token provides full access to the Yandex Music account, so do not make it public or commit it to git; .gitignore already excludes token files and export files. Access can be revoked in devices and services at id.yandex.ru.
Troubleshooting The server does not appear in Claude: check the JSON for missing or extra commas, the project path, and the uv path. Log location: %APPDATA%\Claude\logs\mcp-server-yandex-music.log (Windows) or ~/Library/Logs/Claude/ (macOS). "No token" error: repeat step 3 and keep the terminal open until "Готово!" appears. The error message will list all paths where the server looks for the token. Missing new tools after an update: restart Claude and open a new chat.
Author and license Made by Kenzolika & Claudiea. MIT license, see LICENSE for details. Uses yandex-music (LGPL-3.0) as an unmodified dependency.
