# Music Recommendation MCP Connector

An MCP (Model Context Protocol) server that turns Claude Code into a music
recommendation agent. It's backed by the free [Last.fm API](https://www.last.fm/api)
and exposes 8 tools for artist/track search, similarity-based recommendations,
genre/mood discovery, and personalized recommendations for a Last.fm user.

## Tools exposed

| Tool | What it does |
|---|---|
| `search_artist` | Disambiguate a fuzzy/misspelled artist name |
| `get_artist_info` | Bio, genre tags, listener stats |
| `get_similar_artists` | "More artists like X" |
| `get_top_tracks` | An artist's most popular tracks |
| `get_similar_tracks` | "More songs like this track" |
| `get_top_tracks_by_tag` | Discover tracks by genre/mood (e.g. `chill`, `k-pop`) |
| `get_top_artists_by_tag` | Discover artists by genre/mood |
| `recommend_for_user` | Personalized recs from a Last.fm username's listening history |

## 1. Get a free Last.fm API key

1. Go to https://www.last.fm/api/account/create
2. Fill in the form (app name can be anything, e.g. "My Music Agent")
3. Copy the **API key** it gives you

## 2. Install dependencies

A virtual environment is already set up in `.venv`. To reinstall from scratch:

```powershell
python -m venv .venv
.venv\Scripts\pip install -r requirements.txt
```

## 3. Set your API key

Copy `.env.example` to `.env` and fill in your key, or set the environment
variable directly. The server reads `LASTFM_API_KEY` from the process
environment (it does not load `.env` files itself), so pass it via
`claude mcp add --env` as shown below, or export it in your shell first:

```powershell
$env:LASTFM_API_KEY = "your_key_here"
```

## 4. Register the connector with Claude Code

From this project directory:

```powershell
claude mcp add music-recommendation --env LASTFM_API_KEY=your_key_here -- python "C:\Users\bhoomika\Documents\music-recommendation-mcp\server.py"
```

Verify it's registered:

```powershell
claude mcp list
```

Restart/reopen Claude Code, then just ask it for music recommendations in
plain language, e.g.:

- "Recommend artists similar to Tame Impala"
- "What are some good chill/lo-fi tracks?"
- "Build me a recommendation list based on Last.fm user rj" (a real Last.fm
  username with listening history)
- "What genre is Radiohead tagged as, and who's similar?"

Claude Code will call the connector's tools automatically as needed — this
repo is the connector; Claude Code itself is the agent using it.

## 5. (Optional) Deploy to Render as a remote connector for claude.ai

`claude mcp add` (step 4) only works for Claude Code, since it spawns the
script locally over stdio. claude.ai's web/desktop **Settings > Connectors**
instead needs a server reachable over a URL. `server.py` supports both: it
runs over stdio by default, and switches to streamable-HTTP automatically
when a `PORT` environment variable is present (which Render sets for every
web service).

1. Push this project to a GitHub repo (Render deploys from git):
   ```powershell
   git init
   git add .
   git commit -m "Initial commit"
   ```
   Create a repo on GitHub and push to it (`git remote add origin <url>`,
   `git push -u origin main`).
2. On [render.com](https://render.com), click **New +** → **Blueprint**,
   connect the GitHub repo. Render will detect `render.yaml` and configure
   the web service automatically (Python, `pip install -r requirements.txt`,
   `python server.py`).
3. When prompted (or afterwards under the service's **Environment** tab),
   set `LASTFM_API_KEY` to your Last.fm key. It's marked `sync: false` in
   `render.yaml` so it's never committed to the repo.
4. Wait for the deploy to finish. Render gives you a URL like
   `https://music-recommendation-mcp.onrender.com`.
5. In claude.ai (or the desktop app), go to **Settings → Connectors → Add
   custom connector**, and enter:
   ```
   https://music-recommendation-mcp.onrender.com/mcp
   ```
   (note the `/mcp` path suffix). Save, and the 8 tools should appear.

Notes:
- The free Render plan spins the service down after inactivity, so the
  first request after idling will be slow (cold start) while it wakes up.
- The server has no authentication of its own — anyone with the URL can
  call your Last.fm proxy. That's low-risk for a free, read-only API key,
  but don't put anything sensitive behind this same server later without
  adding auth.

## 6. (Optional) Test the server standalone

```powershell
.venv\Scripts\python server.py
```

This starts the MCP server on stdio and waits for a client (like Claude Code)
to connect — it won't print anything on its own, which is expected.

To sanity-check the Last.fm integration directly without an MCP client:

```powershell
.venv\Scripts\python -c "import asyncio, server; print(asyncio.run(server.get_similar_artists(artist_name='Daft Punk')))"
```

## Notes

- Built against `mcp` SDK v2.x (`MCPServer`, formerly `FastMCP` in v1.x).
- No paid services or OAuth required — Last.fm's API key is free and instant.
- To swap in a different data source (e.g. Spotify or MusicBrainz) later,
  only `server.py`'s `_lastfm_request` helper and the tool bodies need to
  change; the MCP registration step stays the same.