Lastfm

---
name: lastfm
description: >-
  Interact with the Last.fm music data API: lookup user listening history,
  get artist/album/track metadata, discover similar music via collaborative
  filtering, explore global and per-country charts, search by artist/album/track,
  manage tags, and scrobble listening events. Use when the user asks about
  music data, listening statistics, music recommendations, similar artists,
  charts, or wants to scrobble or love tracks.
license: MIT
compatibility: Requires a Last.fm API key in the LASTFM_API_KEY env var.
  For write operations (scrobble, love, now-playing), also needs
  LASTFM_API_SECRET and LASTFM_SESSION_KEY. The `lastfm-cli` CLI tool
  must be on PATH.
metadata:
  tags: [music, lastfm, scrobbling, api-client, music-discovery]
  source: https://www.last.fm/api
---

# Last.fm

## Setup

```bash
export LASTFM_API_KEY="your_api_key_here"
# For write operations only:
export LASTFM_API_SECRET="your_api_secret"
export LASTFM_SESSION_KEY="your_session_key"
```

Get an API key at https://www.last.fm/api/account/create (free, requires a Last.fm account).

## Essential Commands

### User queries — "what am I listening to"

Configurable via `LASTFM_USERNAME` env var. Defaults to `<username>` if unset.

```bash
lastfm-cli user info <username>                      # Profile + stats
lastfm-cli user recent-tracks <username> --limit 10   # Recent listening
lastfm-cli user top-artists <username> --period 7day  # Weekly top artists
lastfm-cli user top-tracks <username> --period overall # All-time faves
lastfm-cli user loved-tracks <username>               # Loved tracks
lastfm-cli user friends <username>                    # Social graph
lastfm-cli user weekly-charts <username>              # Available chart periods
```

### Music Discovery — "what's similar to X"

```bash
lastfm-cli artist similar <artist> --limit 10         # Taste graph neighbors
lastfm-cli artist info <artist>                       # Bio, stats, tags
lastfm-cli artist top-tracks <artist>                 # Their most popular
lastfm-cli track similar <artist> "<track>"           # Track-level similarity
lastfm-cli album info <artist> "<album>"              # Tracklist, metadata
lastfm-cli tag top-artists <tag>                      # Genre browsing
```

### Charts — "what's popular"

```bash
lastfm-cli chart top-artists --limit 20               # Global
lastfm-cli geo top-artists "Japan" --limit 20         # Per-country
lastfm-cli geo top-tracks "Germany" --limit 20
lastfm-cli tag top-tracks "electronic" --limit 15     # By genre tag
```

### Search — "find that thing"

```bash
lastfm-cli artist search "Radiohead"                  # Find by name
lastfm-cli album search "OK Computer"                 # Find albums
lastfm-cli track search "Karma Police"                # Find tracks
```

### Write operations (require session auth)

```bash
lastfm-cli track scrobble "Artist" "Song" --album "Album"
lastfm-cli track now-playing "Artist" "Song"
lastfm-cli track love "Artist" "Song"
```

### Auth flow (one-time setup)

```bash
# 1. Get a token
lastfm-cli auth get-token

# 2. User visits: https://www.last.fm/api/auth/?api_key=KEY&token=TOKEN

# 3. Exchange for session key
lastfm-cli auth get-session <token>
# → Set export LASTFM_SESSION_KEY=<key>
```

## Reference Files

- `references/auth-flow.md` — Full walkthrough for setting up write operation auth (scrobble, love, now-playing). Read this before attempting write operations.

## Music Discovery Pipeline — "find me new stuff I'll like"

The core flow for turning liked tracks into recommendations:

1. **Get user's top artists/tracks** from Last.fm:
   ```bash
   lastfm-cli user top-artists <username> --period 1month --limit 5 --json
   lastfm-cli user top-tracks <username> --period 1month --limit 10 --json
   lastfm-cli user loved-tracks <username> --json
   ```

2. **For each artist, find similar artists** via Last.fm's collaborative filtering:
   ```bash
   lastfm-cli artist similar "<artist>" --limit 5 --json
   ```

3. **For each track, find similar tracks** for more granular recommendations:
   ```bash
   lastfm-cli track similar "<artist>" "<track>" --limit 5 --json
   ```

4. **Cross-reference** against what they've already scrobbled (recent-tracks) to filter out already-heard material.

5. **Check against the user's own collection** (via Radarr/Sonarr/jellyfin-cli or Spotify library) to see what's already in the library vs genuinely new discovery.

## Using with --json for Machine Processing

```bash
# Pipe to jq for structured queries
lastfm-cli artist similar "Radiohead" --limit 5 --json | jq '.similarartists.artist[] | {name, match}'

# Get a user's all-time top artists with playcounts
lastfm-cli user top-artists <username> --period overall --limit 3 --json | jq '.topartists.artist[] | {name, playcount}'

# Find most popular tracks by a genre
lastfm-cli tag top-tracks "electronic" --limit 10 --json | jq '.tracks.track[] | {name, artist: .artist.name, listeners}'
```

## Known Gotchas

- **API key required for EVERY request.** The key is free — get one at the Last.fm API account page.
- **Rate limit is ~5 req/sec sustained.** The API docs say "be reasonable" — if you're making several calls per second continuously, your account may be suspended. Add small delays in loops.
- **User-Agent header matters.** The CLI sends `lastfm-cli/1.0 (hermes-agent)`. Last.fm's docs explicitly ask for an identifiable User-Agent.
- **XML is the default response format.** The CLI requests `format=json`. Without it, responses come back as XML.
- **Artist names can be misspelled.** Use `--autocorrect` flag on artist commands to let Last.fm correct misspellings.
- **Write operations need auth setup.** scrobble, love, and now-playing require a full auth flow (token → session key). Read-only endpoints don't.
- **The collaborative filtering graph is NOT social.** `artist.getSimilar` returns algorithmic similarity based on aggregate listening patterns, not human-curated recommendations.
- **Timestamps for scrobbles** are UNIX epoch seconds. If omitted, uses current time.
- **`--from` and `--to` on recent-tracks** accept ISO 8601 date strings (e.g., `2026-05-27`).
- **Period values**: `overall`, `7day`, `1month`, `3month`, `6month`, `12month`.

## When to Reach for This Tool

- User asks "what's [person] listening to lately?"
- User wants music discovery: "find me artists similar to..."
- User wants listening statistics: top artists, tracks, albums by period
- User wants geographic music trends: "what's popular in [country]"
- User wants genre exploration via tags
- User wants to scrobble or love tracks programmatically
- Any question about music metadata, artist info, album tracklists