Unofficial Yandex Music server: search, likes, history, My Wave, playlists. Token stays local.
Неофициальный MCP-сервер для Яндекс Музыки. Подключается к Claude Desktop, Claude Code и другим MCP-клиентам и даёт ассистенту доступ к вашей библиотеке: лайкам, истории прослушиваний, «Моей волне» и плейлистам.
Сервер работает локально на вашем компьютере (stdio). Токен хранится только у вас и никуда не передаётся. Поддерживаются Windows, macOS и Linux.
⚠️ Неофициальный проект. Не связан с ООО «Яндекс» и не одобрен им. Использует неофициальную библиотеку yandex-music: если Яндекс изменит 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 — рекомендации и чарт |
Воспроизведением сервер не управляет: музыку вы слушаете, как обычно, в приложении Яндекс Музыки, а новые плейлисты и лайки появляются там сразу.
1. Установите uv — он скачает и запустит коннектор:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
curl -LsSf https://astral.sh/uv/install.sh | sh
Закройте терминал, откройте заново и проверьте: uv --version.
2. Войдите в Яндекс (один раз):
uvx --from yandex-music-mcp yandex-music-mcp-auth
3. Подключите к клиенту:
claude mcp add yandex-music -- uvx yandex-music-mcp
claude_desktop_config.json:
{
"mcpServers": {
"yandex-music": {
"command": "uvx",
"args": ["yandex-music-mcp"]
}
}
}
Если что-то не получилось, ниже — пошаговая установка из исходников с подробностями.
Понадобятся 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.
git clone https://github.com/kenzolika/yandex-music-mcp.git
Или нажмите Code → Download ZIP на странице репозитория и распакуйте архив.
cd yandex-music-mcp
uv run yandex-music-mcp-auth
Откроется страница входа Яндекса (ya.ru/device), а в терминале появится код. Войдите в аккаунт, введите код и дождитесь в терминале строки «Готово!». Токен сохранится в ~/.yandex-music-mcp/token. Скрипт использует официальный вход Яндекса и вашего пароля не видит.
Клиенту нужно знать, где лежит проект. Самый простой способ — в терминале, в папке проекта (после шага 3 вы уже в ней):
(Get-Location).Path → например, C:\Users\Ivan\Documents\yandex-music-mcppwd → например, /Users/ivan/yandex-music-mcpНа Windows можно и мышкой: в Проводнике зажмите Shift, щёлкните по папке правой кнопкой и выберите «Копировать как путь».
Важно для Windows: в JSON-конфиге обратный слэш нужно удваивать:
C:\\Users\\Ivan\\Documents\\yandex-music-mcp. Можно вместо этого писать прямые слэши — Windows их понимает:C:/Users/Ivan/Documents/yandex-music-mcp.
В Claude Desktop откройте Settings → Developer → Edit Config — откроется файл claude_desktop_config.json. Добавьте в него блок mcpServers, подставив свой путь из шага 4:
{
"mcpServers": {
"yandex-music": {
"command": "uv",
"args": ["--directory", "C:/Users/Ivan/Documents/yandex-music-mcp", "run", "yandex-music-mcp"]
}
}
}
"mcpServers": { ... } на верхний уровень рядом с ними, отделив запятой.uv? Укажите в "command" полный путь к нему. Его покажет where.exe uv (Windows) или which uv (macOS/Linux) — обычно это C:/Users/Ivan/.local/bin/uv.exe или ~/.local/bin/uv.Полностью закройте Claude Desktop (на Windows — через значок в трее → Quit, крестика окна недостаточно) и откройте снова.
Вместо шага 5а — одна команда с путём из шага 4:
claude mcp add yandex-music -- uv --directory "C:/Users/Ivan/Documents/yandex-music-mcp" run yandex-music-mcp
Напишите в новом чате: «Проверь подключение к Яндекс Музыке». Если в ответе ваш логин — всё работает.
| Переменная | Назначение |
|---|---|
YANDEX_MUSIC_TOKEN | Токен напрямую (вместо файла) |
YANDEX_MUSIC_TOKEN_FILE | Путь к файлу с токеном |
YANDEX_MUSIC_EXPORT_DIR | Куда сохранять выгрузки (по умолчанию Документы/Yandex Music exports) |
.gitignore уже исключает файлы токена и выгрузки.delete_playlist дополнительно требует точное название плейлиста.uv. Логи: %APPDATA%\Claude\logs\mcp-server-yandex-music.log (Windows) или ~/Library/Logs/Claude/ (macOS).Unofficial MCP server for Yandex Music. It connects Claude Desktop, Claude Code and other MCP clients to your Yandex Music library: likes, listening history, My Wave and playlists.
The server runs locally on your machine (stdio). Your token is stored only on your computer and is never sent anywhere else. Works on Windows, macOS and Linux.
⚠️ Unofficial project. Not affiliated with or endorsed by Yandex. Built on the unofficial yandex-music library, so it may break temporarily if Yandex changes its API. The server does not download audio; it only works with metadata, likes and playlists in your account.
| Read | Write |
|---|---|
account_info — check the connection | create_playlist — new playlist (private by default) |
search — tracks, albums, artists, playlists | add_tracks_to_playlist |
get_liked_tracks — your liked tracks | remove_tracks_from_playlist |
get_listening_history — history by day | delete_playlist — delete a playlist (requires its exact title) |
list_my_playlists, get_playlist_tracks — your playlists | like_tracks / unlike_tracks |
get_playlist_by_url — any public playlist or album by link | export_tracks_to_file — export likes or a playlist to .txt and .csv |
get_album_tracks, get_artist_tracks | |
get_similar_tracks, get_my_wave, get_chart — recommendations and charts |
The server does not control playback: listen in the Yandex Music app as usual; new playlists and likes show up there immediately.
Example prompts: "Analyze my last 300 likes: which genres and decades do I listen to?" · "What did I listen to this week?" · "Build a private playlist 'Autumn' with 25 tracks similar to my recent likes" · "Here's my friend's playlist: . Which of these tracks are already in my likes?" · "Export all my likes to a file"
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"; macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh. Reopen the terminal and check uv --version.uvx --from yandex-music-mcp yandex-music-mcp-authclaude mcp add yandex-music -- uvx yandex-music-mcpclaude_desktop_config.json:
{
"mcpServers": {
"yandex-music": { "command": "uvx", "args": ["yandex-music-mcp"] }
}
}
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"; macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh. Reopen the terminal and check uv --version.git clone https://github.com/kenzolika/yandex-music-mcp.git, or Code → Download ZIP on the repository page.cd yandex-music-mcp, then uv run yandex-music-mcp-auth. A Yandex sign-in page (ya.ru/device) opens and a code appears in the terminal. Sign in, enter the code and wait for the "Готово!" ("Done!") line. The token is saved to ~/.yandex-music-mcp/token. This is Yandex's official OAuth device flow; the script never sees your password.(Get-Location).Path (Windows PowerShell) or pwd (macOS/Linux). On Windows you can also Shift + right-click the folder in Explorer → Copy as path. In JSON, either double the backslashes (C:\\Users\\Ivan\\yandex-music-mcp) or use forward slashes (C:/Users/Ivan/yandex-music-mcp).claude_desktop_config.json. Add:
{
"mcpServers": {
"yandex-music": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/yandex-music-mcp", "run", "yandex-music-mcp"]
}
}
}
"mcpServers" next to them, separated by a comma. If Claude can't find uv, put its full path in "command" (where.exe uv on Windows, which uv on macOS/Linux). Then fully quit Claude Desktop (on Windows: tray icon → Quit) and start it again.claude mcp add yandex-music -- uv --directory /absolute/path/to/yandex-music-mcp run yandex-music-mcp| Variable | Purpose |
|---|---|
YANDEX_MUSIC_TOKEN | Pass the token directly instead of a file |
YANDEX_MUSIC_TOKEN_FILE | Path to the token file |
YANDEX_MUSIC_EXPORT_DIR | Where exports are saved (default: Documents/Yandex Music exports) |
.gitignore already excludes token files and exports.delete_playlist also requires the playlist's exact title.uv. Logs: %APPDATA%\Claude\logs\mcp-server-yandex-music.log (Windows) or ~/Library/Logs/Claude/ (macOS).Сделано Kenzolika & Claudiea 🎧 — человеком и его ИИ-напарницей (Claude) за один осенний вечер. Made by Kenzolika & Claudiea, a human and his AI sidekick (Claude), in one autumn evening.
MIT, см. LICENSE. Использует библиотеку yandex-music (LGPL-3.0) как зависимость, без изменений. MIT, see LICENSE. Uses yandex-music (LGPL-3.0) as an unmodified dependency.
Source-derived launch command. Check the maintainer’s required arguments and credentials before running:
uvx yandex-music-mcpMerge this template into ~/Library/Application Support/Claude/claude_desktop_config.json. Keep existing servers. Add any arguments, credentials, and permissions required by the maintainer; this template has not been install-tested.
{
"mcpServers": {
"io-github-kenzolika-yandex-music-mcp": {
"command": "uvx",
"args": [
"yandex-music-mcp"
]
}
}
}Restart Claude Desktop completely for changes to take effect. Confirm the server appears connected in the client’s tool list, then try a read-only example from its documentation.
Claude Desktop setup referenceyandex-music-mcppypiYandex Music (unofficial) works with any MCP-compatible client. Copy the config snippet from the Configuration section above and add it to the file shown for your client, then restart the application.
~/Library/Application Support/Claude/claude_desktop_config.jsonRestart Claude Desktop completely for changes to take effect.~/.cursor/mcp.jsonRestart Cursor for changes to take effect..vscode/mcp.jsonReload VS Code window for changes to take effect.~/.codeium/windsurf/mcp_config.jsonRestart Windsurf for changes to take effect..mcp.jsonSave at the project root, then start Claude Code in that project and review the MCP server approval prompt. Keep real credentials out of shared files.