setlist-mcp
MCP server for setlist.fm — search concert setlists, artists, venues, and tours via natural language. Read-only (setlist.fm has no write API).
Setup
Option A — npx (recommended)
Add to .mcp.json in your project or ~/.claude/mcp.json:
{
"mcpServers": {
"setlist": {
"command": "npx",
"args": ["-y", "setlist-mcp"],
"env": {
"SETLIST_API_KEY": "your-api-key-here"
}
}
}
}
Option B — from source
git clone https://github.com/chrischall/setlist-mcp
cd setlist-mcp
npm install && npm run build
Then add to .mcp.json:
{
"mcpServers": {
"setlist": {
"command": "node",
"args": ["/path/to/setlist-mcp/dist/index.js"],
"env": {
"SETLIST_API_KEY": "your-api-key-here"
}
}
}
}
Or use a .env file in the project directory with SETLIST_API_KEY=.
Getting your API key
Apply for a free API key (non-commercial use) at setlist.fm/settings/api — you'll need a setlist.fm account. The key is sent as the x-api-key header on every request.
Optional: set SETLIST_ACCEPT_LANGUAGE (one of en, es, fr, de, pt, tr, it, pl) to localize city/country names.
All tools are read-only and prefixed setlist_.
Artists
setlist_search_artists — find artists by artistName or artistMbid; returns each artist's MusicBrainz ID (mbid).setlist_get_artist — get an artist by mbid.setlist_get_artist_setlists — an artist's setlists (most recent first), by mbid, paginated via p.
Setlists
setlist_search_setlists — search by any mix of artist, venue, city, country, tour, date (ISO yyyy-MM-dd), or year.setlist_get_setlist — a setlist (with full song list) by setlistId.setlist_get_setlist_version — a specific historical version by versionId.
Batch
setlist_resolve_concerts — resolve up to 24 {artist, date, city?, venue?} to their best-match setlists in one call (with songCount/hasSongs + a {matched, stubs, tourReferenced, unmatched, pending} summary). When a show is an empty stub but the act toured a repeating set, the result also includes a tourReference — a populated, representative setlist from the same tour on a nearby date (with songs + its own url), clearly labeled as a reference, not the exact show (pass tourFallback: false to skip). Calls are paced to setlist.fm's rate limit; if a batch can't finish in time the rest come back pending: true — re-call with just those. For more than 24 shows, chunk into batches of ≤24.
Venues
setlist_search_venues — find venues by name and/or location.setlist_get_venue — get a venue by venueId.setlist_get_venue_setlists — setlists performed at a venue, paginated via p.
Cities & countries
setlist_search_cities — find cities by name/location; returns each city's geoId.setlist_get_city — get a city by geoId.setlist_search_countries — list all supported countries and their codes.
Users
setlist_get_user — a user's public profile by userId.setlist_get_user_attended — concerts a user marked as attended.setlist_get_user_edited — setlists a user has created or edited.
Utility
setlist_healthcheck — verify the API key works and the API is reachable.
Typical flows
- "What did Radiohead play at their last show?" →
setlist_search_artists (Radiohead → mbid) → setlist_get_artist_setlists (latest) → setlist_get_setlist for the song list.
- "Setlists at Red Rocks in 2023" →
setlist_search_venues (Red Rocks → venueId) → setlist_search_setlists with venueId + year: 2023.
- "Phish on 2023-08-07" →
setlist_search_setlists with artistName: "Phish", date: "2023-08-07".
Attribution & API terms
setlist.fm's API terms bind anyone using this data. When you present setlist.fm results to a user:
- Always cite the source. Each setlist/artist/venue result includes a
url — show it as a real, clickable link to setlist.fm (e.g. "Source: The Beatles setlist on setlist.fm"). The terms require a followable link — never a nofollow. If a particular result has no url, link to https://www.setlist.fm instead.
- Non-commercial use only. A free API key covers non-commercial use; commercial use needs setlist.fm's permission.
- Live data, not a datastore. The terms forbid persistent caching — this server fetches fresh on every call and you should treat results as point-in-time, not build a local copy.
- Don't expose or share the API key. It's read from
SETLIST_API_KEY and never appears in results.
Interpreting setlist data
- Songs live in
sets.set[]; each set may have an encore number (1 = first encore) and a name (e.g. an acoustic set or a full album).
- Each
song may carry: tape: true (a pre-recorded intro/outro — not actually performed live), cover (the original artist when it's a cover), with (a guest performer), and info (a note like "acoustic" or "first time live"). Surface these when relevant rather than dropping them.
Notes
- Stub setlists: every setlist result carries
songCount / setCount / hasSongs. A page can exist with no songs logged (hasSongs: false) — skip those without a second get_setlist call.
- Disambiguate by location:
artistName + date can return shows in multiple cities. Add cityName/cityId or venueName/venueId to pin the right one (e.g. TSO on a date plays both Charlotte and Orlando).
- All performers at a venue/festival on a day: call
setlist_search_setlists with venueName (or venueId) + date and no artist.
- IDs chain:
search_* tools return the mbid / setlistId / venueId / geoId you feed into the get_* tools.
- All dates are ISO
yyyy-MM-dd — both the date/lastUpdated inputs and every eventDate in the output. (The server translates to/from setlist.fm's native dd-MM-yyyy internally.)
- Results are paginated; pass
p (1-based) to page through large result sets.
- setlist.fm rate-limits the standard tier (~2 req/sec); a 429 is retried once.