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).

• npm: npmjs.com/package/setlist-mcp
• Source: github.com/chrischall/setlist-mcp

Setup#

Option A — npx (recommended)#

Add to .mcp.json in your project or ~/.claude/mcp.json:

json

{
  "mcpServers": {
    "setlist": {
      "command": "npx",
      "args": ["-y", "setlist-mcp"],
      "env": {
        "SETLIST_API_KEY": "your-api-key-here"
      }
    }
  }
}

Option B — from source#

bash

git clone https://github.com/chrischall/setlist-mcp
cd setlist-mcp
npm install && npm run build

Then add to .mcp.json:

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=<value>.

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.

Tools#

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.