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:

{
  "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=\x3Cvalue>.

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 (dd-MM-yyyy), or year.
• setlist_get_setlist — a setlist (with full song list) by setlistId.
• setlist_get_setlist_version — a specific historical version by versionId.

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: "07-08-2023" (note the dd-MM-yyyy format).

Notes

• IDs chain: search_* tools return the mbid / setlistId / venueId / geoId you feed into the get_* tools.
• date filters use dd-MM-yyyy (e.g. 07-08-2023 = 7 August 2023).
• 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.