# saavn-mcp

A small **Model Context Protocol server** that lets an AI agent put music into a self-hosted
[Navidrome](https://www.navidrome.org/) library. Ask your assistant for a song in plain language, and it lands, tagged with cover art, in your library a few seconds later.

I run it on my homelab behind a chat agent: "add Kesariya by Arijit Singh" from my phone and
the track is in Navidrome before I open the app.

```
chat agent ──MCP (streamable HTTP)──► server.py  ── download_song(query) ──►  saavn_dl.py
                                                                               │ search / resolve URL
                                                                               │ fetch 320 kbps AAC
                                                                               │ tag + cover art
                                                                               ▼
                                                   MUSIC_DIR/<Artist> - <Album> [Year]/NN. Title.m4a
                                                                               │
                                                     Navidrome startScan (Subsonic token auth) ◄┘
```

## Tool

| Tool | Input | Does |
|---|---|---|
| `download_song` | a plain-text query (`"Arjan Dhillon Pindan De Naa"`) or a JioSaavn song/album/playlist URL | picks the best match, downloads into the library, triggers a rescan, returns a summary or a clear `FAILED:` reason |

Agent-friendly by design: search queries auto-select the top result instead of prompting, errors
come back as text the agent can relay, and a 120 s timeout stops a stuck download from
hanging the agent.

## Pieces

- **`server.py`**: the MCP server ([FastMCP](https://github.com/jlowin/fastmcp)), streamable HTTP on
  `127.0.0.1:18811/mcp`.
- **`saavn_dl.py`**: the downloader CLI, usable on its own:
  `saavn_dl.py "query"`, `saavn_dl.py -y "query"`, `saavn_dl.py <url>`. It subclasses the downloader from
  [bunnykek/jiosaavn-dl](https://github.com/bunnykek/jiosaavn-dl) and adds search, Navidrome-style
  `Artist - Album [Year]` folders, cover art, skip-if-exists, clean error handling and the library
  rescan. The rescan uses Subsonic **salted-token auth**, so the password never goes over the wire.

## Setup

```bash
git clone https://github.com/bunnykek/jiosaavn-dl ~/jiosaavn-dl
pip install -r ~/jiosaavn-dl/requirements.txt -r requirements.txt
cp .env.example .env   # set MUSIC_DIR and the Navidrome account
set -a; . ./.env; set +a
python server.py
```

Then point any MCP client at `http://127.0.0.1:18811/mcp`. `saavn-mcp.service` is a systemd unit
for running it permanently.

| Env var | Default |
|---|---|
| `MUSIC_DIR` | `~/Music` |
| `NAVIDROME_URL` / `NAVIDROME_USER` / `NAVIDROME_PASS` | `http://localhost:4533` /, /, (rescan skipped if unset) |
| `JIOSAAVN_DL_DIR` | `~/jiosaavn-dl` |
| `SAAVN_MCP_HOST` / `SAAVN_MCP_PORT` | `127.0.0.1` / `18811` |

For personal use with content you're entitled to. MIT licensed (the jiosaavn-dl dependency is
fetched separately and is not included here).