Content
# Yandex Music MCP Server
MCP server for creating playlists on Yandex Music. Thin wrapper around [yandex-music-api](https://github.com/MarshalX/yandex-music-api).
## Features
Three MCP tools exposed over stdio:
- `create_playlist(title, visibility="public")` — create a new playlist.
- `search_tracks(query, limit=10)` — search tracks by free-text query, returns `track_id` and `album_id`.
- `add_tracks_to_playlist(kind, tracks)` — append the found tracks to a playlist.
Requires Python 3.8+.
## Quick start with `uvx` (no install)
If you have [`uv`](https://github.com/astral-sh/uv):
```bash
# one-time: get a token
uvx --from git+https://github.com/lappi/yandex-music-mcp yandex-music-mcp-token
# run the server
YANDEX_MUSIC_TOKEN=<token> \
uvx --from git+https://github.com/lappi/yandex-music-mcp yandex-music-mcp
```
Once the package is published to PyPI the `--from ...` flag will no longer be needed.
## Install with pip
```bash
git clone https://github.com/lappi/yandex-music-mcp
cd yandex-music-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e .
```
This creates two console scripts inside the venv:
- `yandex-music-mcp` — the MCP server.
- `yandex-music-mcp-token` — OAuth device-flow token helper.
## Getting a token
**Recommended — OAuth device flow:**
```bash
yandex-music-mcp-token
```
The command prints a URL (`https://ya.ru/device`) and a short code. Open the URL in any browser, sign in to your Yandex account and enter the code. The access token is printed to stdout.
One-liner into env:
```bash
export YANDEX_MUSIC_TOKEN=$(yandex-music-mcp-token)
```
**Caveat:** the helper uses the `client_id`/`client_secret` of the Yandex Music mobile app (publicly known). Yandex Music has no official public API — this technically violates the ToS, so use at your own risk.
Alternative token sources: https://music-yandex-bot.ru/, browser extensions, Android APK — see the [yandex-music-api token docs](https://yandex-music.readthedocs.io/en/main/token.html).
## Running the server
```bash
YANDEX_MUSIC_TOKEN=<token> yandex-music-mcp
```
Or as a module:
```bash
python -m yandex_music_mcp
```
The server speaks MCP over stdio and waits for a client.
## Hooking up to Claude Code / Claude Desktop
Add an entry to your MCP config:
- Claude Code: `~/.claude.json`
- Claude Desktop (macOS): `~/Library/Application Support/Claude/claude_desktop_config.json`
- Claude Desktop (Windows): `%APPDATA%\Claude\claude_desktop_config.json`
### With `uvx` (recommended for end users)
```json
{
"mcpServers": {
"yandex-music": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/lappi/yandex-music-mcp",
"yandex-music-mcp"
],
"env": { "YANDEX_MUSIC_TOKEN": "<your-token>" }
}
}
}
```
### With a local venv
```json
{
"mcpServers": {
"yandex-music": {
"command": "/absolute/path/to/yandex-music-mcp/.venv/bin/yandex-music-mcp",
"env": { "YANDEX_MUSIC_TOKEN": "<your-token>" }
}
}
}
```
Fully quit and relaunch Claude Desktop (`Cmd+Q` / `Alt+F4`) after editing the config — closing the window does not reload it.
## Debugging with MCP Inspector
```bash
YANDEX_MUSIC_TOKEN=<token> npx @modelcontextprotocol/inspector yandex-music-mcp
```
## Example usage
Ask the LLM: *"Create a playlist 'Classic Rock' and add 5 Queen tracks to it."*
The LLM will chain `create_playlist` → `search_tracks` → `add_tracks_to_playlist`.
## License
MIT. This project is not affiliated with or endorsed by Yandex.
