Yandex Music MCP
An unofficial Yandex Music MCP server that lets you browse, analyze, and manage your Yandex Music library from Claude.
Check account connection, login, and Plus subscription status.
Search Yandex Music for tracks, albums, artists, and playlists.
Read liked tracks, listening history by day, your playlists, playlist tracks, album tracks, artist top tracks, similar tracks, My Wave recommendations, and the current chart.
Create new playlists (private by default) and add/remove tracks in your playlists.
Like and unlike tracks.
Export all liked tracks or a playlist to local .txt and .csv files.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Yandex Music MCP what did I listen to this week?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
yandex-music-mcp
Неофициальный MCP-сервер для Яндекс Музыки. Подключается к Claude Desktop, Claude Code и другим MCP-клиентам и даёт ассистенту доступ к вашей библиотеке: лайкам, истории прослушиваний, «Моей волне» и плейлистам.
Сервер работает локально на вашем компьютере (stdio). Токен хранится только у вас и никуда не передаётся. Поддерживаются Windows, macOS и Linux.
⚠️ Неофициальный проект. Не связан с ООО «Яндекс» и не одобрен им. Использует неофициальную библиотеку yandex-music: если Яндекс изменит API, сервер может временно перестать работать. Аудио сервер не скачивает — только работает с метаданными, лайками и плейлистами вашего аккаунта.
Что умеет
Чтение | Изменения |
|
|
|
|
|
|
|
|
|
|
|
|
| |
|
Воспроизведением сервер не управляет: музыку вы слушаете, как обычно, в приложении Яндекс Музыки, а новые плейлисты и лайки появляются там сразу.
Примеры запросов
«Проанализируй мои последние 300 лайков: какие жанры и десятилетия я слушаю?»
«Что я слушал на этой неделе?»
«Собери приватный плейлист "Осень" из 25 треков, похожих на мои последние лайки»
«Вот плейлист друга: <ссылка>. Что из него уже есть в моих лайках?»
«Выгрузи все мои лайки в файл»
Related MCP server: youtube-music-cli-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. Войдите в Яндекс (один раз):
uvx --from yandex-music-mcp yandex-music-mcp-auth3. Подключите к клиенту:
Claude Code — одна команда:
claude mcp add yandex-music -- uvx yandex-music-mcpClaude 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-mcpmacOS / 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. Добавьте в него блок mcpServers, подставив свой путь из шага 4:
{
"mcpServers": {
"yandex-music": {
"command": "uv",
"args": ["--directory", "C:/Users/Ivan/Documents/yandex-music-mcp", "run", "yandex-music-mcp"]
}
}
}В файле уже есть другие настройки? Не удаляйте их: добавьте
"mcpServers": { ... }на верхний уровень рядом с ними, отделив запятой.Claude не находит
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б. Или подключите к Claude Code
Вместо шага 5а — одна команда с путём из шага 4:
claude mcp add yandex-music -- uv --directory "C:/Users/Ivan/Documents/yandex-music-mcp" run yandex-music-mcp6. Проверьте
Напишите в новом чате: «Проверь подключение к Яндекс Музыке». Если в ответе ваш логин — всё работает.
Настройки
Переменная | Назначение |
| Токен напрямую (вместо файла) |
| Путь к файлу с токеном |
| Куда сохранять выгрузки (по умолчанию |
Безопасность и приватность
Токен даёт полный доступ к вашему аккаунту Музыки. Не публикуйте его и не добавляйте в 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 и откройте новый чат.
English
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.
Tools
Read | Write |
|
|
|
|
|
|
|
|
|
|
|
|
| |
|
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"
Quick install
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. Reopen the terminal and checkuv --version.Sign in to Yandex (once):
uvx --from yandex-music-mcp yandex-music-mcp-authConnect a client:
Claude Code:
claude mcp add yandex-music -- uvx yandex-music-mcpClaude Desktop: open Settings → Developer → Edit Config and add to
claude_desktop_config.json:{ "mcpServers": { "yandex-music": { "command": "uvx", "args": ["yandex-music-mcp"] } } }
Install from source
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. Reopen the terminal and checkuv --version.Get the code:
git clone https://github.com/kenzolika/yandex-music-mcp.git, or Code → Download ZIP on the repository page.Get a token (once):
cd yandex-music-mcp, thenuv 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.Find the full path to the project folder. In the project folder run
(Get-Location).Path(Windows PowerShell) orpwd(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).Connect a client.
Claude Desktop: Settings → Developer → Edit Config opens
claude_desktop_config.json. Add:{ "mcpServers": { "yandex-music": { "command": "uv", "args": ["--directory", "/absolute/path/to/yandex-music-mcp", "run", "yandex-music-mcp"] } } }Keep any existing settings and add
"mcpServers"next to them, separated by a comma. If Claude can't finduv, put its full path in"command"(where.exe uvon Windows,which uvon macOS/Linux). Then fully quit Claude Desktop (on Windows: tray icon → Quit) and start it again.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 answer shows your login, you're all set.
Configuration
Variable | Purpose |
| Pass the token directly instead of a file |
| Path to the token file |
| Where exports are saved (default: |
Security and privacy
The token gives full access to your Yandex Music account. Never publish or commit it;
.gitignorealready excludes token files and exports.You can revoke access at id.yandex.ru under devices and services.
Every tool that changes something is marked as such for the MCP client, so Claude asks for confirmation before calling it.
delete_playlistalso requires the playlist's exact title.
Troubleshooting
The server doesn't show up in Claude. Check the JSON for missing or extra commas, the project path and the path to
uv. Logs:%APPDATA%\Claude\logs\mcp-server-yandex-music.log(Windows) or~/Library/Logs/Claude/(macOS)."No token" error. Run step 3 again and keep the terminal open until "Готово!" appears. The error message lists every path where the server looked for the token.
New tools are missing after an update. Restart Claude and open a new chat.
Авторы · Authors
Сделано Kenzolika & Claudiea 🎧 — человеком и его ИИ-напарницей (Claude) за один осенний вечер. Made by Kenzolika & Claudiea, a human and his AI sidekick (Claude), in one autumn evening.
Лицензия · License
MIT, см. LICENSE. Использует библиотеку yandex-music (LGPL-3.0) как зависимость, без изменений. MIT, see LICENSE. Uses yandex-music (LGPL-3.0) as an unmodified dependency.
Available Tools
19 toolsaccount_infoARead-only
Проверка подключения: логин, имя и статус подписки Плюс.
Inputs: no named parameters. Returns: object
add_tracks_to_playlistC
Добавляет треки в мой плейлист. track_ids — id из других инструментов ("123:456" или "123").
Inputs: kind (required), track_ids (required), at_start. Returns: object
create_playlistB
Создаёт новый плейлист (по умолчанию приватный). Возвращает его kind.
Inputs: title (required), visibility. Returns: object
delete_playlistADestructive
НЕОБРАТИМО удаляет мой плейлист целиком. Перед вызовом обязательно спроси пользователя. confirm_title — точное название удаляемого плейлиста (защита от удаления не того плейлиста).
Inputs: kind (required), confirm_title (required). Returns: object
export_tracks_to_fileA
Выгружает ВСЕ треки (лайки или плейлист) в текстовые файлы на компьютер, не загружая их в чат: .txt («Исполнитель — Название», по строке) и .csv (с альбомом, годом, жанром, id; для лайков — дата лайка). Файлы кладутся в «Документы/Yandex Music exports» (или в YANDEX_MUSIC_EXPORT_DIR). Для source="playlist" нужен kind.
Inputs: kind, source, file_name, owner_uid. Returns: object
get_album_tracksCRead-only
Информация об альбоме и его треклист.
Inputs: album_id (required). Returns: object
get_artist_tracksCRead-only
Популярные треки артиста.
Inputs: artist_id (required), limit. Returns: object
get_chartCRead-only
Текущий чарт Яндекс Музыки.
Inputs: limit. Returns: object
get_liked_tracksARead-only
Треки из «Мне нравится», от последних лайков к старым, с датой лайка (liked_at). Для анализа вкуса бери limit побольше (до 500).
Inputs: limit, offset. Returns: object
get_listening_historyBRead-only
Недавно прослушанные треки (история прослушиваний), сгруппированные по дням.
Inputs: limit. Returns: object
get_my_waveARead-only
Порция треков из «Моей волны» — персональных рекомендаций. batches — сколько порций (≈5 треков каждая).
Inputs: batches. Returns: object
get_playlist_by_urlARead-only
Треки по ссылке на Яндекс Музыку — в том числе чужого публичного плейлиста. Понимает ссылки вида music.yandex.ru/users/<логин>/playlists/<номер>, music.yandex.ru/playlists/ (новый формат, в т.ч. lk.…) и ссылки на альбом /album/. Подходит любой домен Яндекс Музыки (.ru, .com, .by, .kz и т.д.).
Inputs: url (required), limit. Returns: object
get_playlist_tracksBRead-only
Треки плейлиста. По умолчанию — мой плейлист; owner_uid — для чужого публичного.
Inputs: kind (required), limit, owner_uid. Returns: object
get_similar_tracksBRead-only
Похожие треки по версии Яндекса (track_id в формате "123" или "123:456").
Inputs: track_id (required). Returns: object
like_tracksC
Ставит лайк («Мне нравится») трекам.
Inputs: track_ids (required). Returns: object
list_my_playlistsARead-only
Все мои плейлисты (kind — идентификатор плейлиста для других инструментов).
Inputs: no named parameters. Returns: result
remove_tracks_from_playlistCDestructive
Удаляет указанные треки из моего плейлиста.
Inputs: kind (required), track_ids (required). Returns: object
searchBRead-only
Поиск по каталогу Яндекс Музыки. type сужает поиск; limit — сколько результатов в каждой категории.
Inputs: query (required), type, limit. Returns: object
unlike_tracksCDestructive
Убирает треки из «Мне нравится».
Inputs: track_ids (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 19 tools
Most tools target a clearly distinct resource+action pair: liked tracks, charts, playlists, albums, artists, search, history, wave, and export are all separable. The only real friction is between get_playlist_tracks, get_playlist_by_url, and get_album_tracks, where the same content can be reached via id, owner_uid, or URL — descriptions mostly resolve this but an agent may still hesitate on which entry point to use.
Strong consistent snake_case verb_noun pattern across nearly all tools (get_liked_tracks, create_playlist, add_tracks_to_playlist, export_tracks_to_file, list_my_playlists). Two deviations break it: bare 'search' and the noun-phrase 'account_info' (would be get_account_info / search_catalog), plus a couple of prepositional variants.
At 19 tools the set is on the heavier side but each tool maps to a concrete capability of the music service, with no filler or near-duplicates. Nothing feels padded, though it brushes the upper bound of easy scannability for an agent.
Playlist lifecycle is largely covered (create, list, get tracks, add/remove tracks, delete, export) alongside liked tracks, search, charts, history, and radio-style discovery. Gaps are minor: no playlist rename/edit (title, description, cover), no direct get_track_by_id for track-level metadata, and no liked-albums/artists management.
Maintenance
Related MCP Connectors
MCP server for Yoto: manage cards, tracks, icons and family devices from any MCP client.
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
Read, search and manage iCloud Mail, Calendar and Contacts from Claude and other MCP clients.
Zotero MCP server for Claude and ChatGPT: search, citations, safe writes, PDF passages and pages.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that turns Yandex Music into tools an AI agent can call directly — search, queue, play, build playlists — with no browser involved.1MIT
- AlicenseNot gradedqualityDmaintenanceProvides a local stdio MCP server for controlling YouTube Music through the CLI, enabling playback, search, queue management, and library access via MCP-compatible clients.MIT
- FlicenseNot gradedqualityCmaintenanceEnables AI coding tools and MCP hosts to search YouTube Music and add or remove tracks on your own playlists through natural-language prompts, authenticated with your Google login. It runs locally over stdio, so credentials and OAuth tokens stay on your machine.-
- FlicenseNot gradedqualityAmaintenanceEnables MCP clients like Claude, Cursor, Cline, and Windsurf to search and browse the Apple Music catalog and your library, manage playlists and folders, and control playback, volume, and the Up Next queue. It works on macOS, Windows, and Linux through four selectable engines — native Music.app, the Apple Music API, Safari MusicKit, or a Chrome web player — requiring only a Mac or an Apple Music subscription.-