setlist-mcp 0.1.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "setlist-mcp",
+  "owner": {
+    "name": "Chris Hall",
+    "email": "chris.c.hall@gmail.com"
+  },
+  "metadata": {
+    "description": "MCP server for setlist.fm — concert setlists, artists, venues, and tours via the setlist.fm API",
+    "version": "0.1.0"
+  },
+  "plugins": [
+    {
+      "name": "setlist-mcp",
+      "displayName": "setlist.fm",
+      "source": "./",
+      "description": "MCP server for setlist.fm — search concert setlists, artists, venues, and tours via natural language",
+      "version": "0.1.0",
+      "author": {
+        "name": "Chris Hall"
+      },
+      "homepage": "https://github.com/chrischall/setlist-mcp",
+      "repository": "https://github.com/chrischall/setlist-mcp",
+      "license": "MIT",
+      "keywords": [
+        "setlist.fm",
+        "setlists",
+        "concerts",
+        "mcp"
+      ],
+      "category": "music"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "setlist-mcp",
+  "displayName": "setlist.fm",
+  "version": "0.1.0",
+  "description": "MCP server for setlist.fm — search concert setlists, artists, venues, and tours via the setlist.fm API",
+  "author": {
+    "name": "Chris Hall",
+    "email": "chris.c.hall@gmail.com"
+  },
+  "homepage": "https://github.com/chrischall/setlist-mcp",
+  "repository": "https://github.com/chrischall/setlist-mcp",
+  "license": "MIT",
+  "keywords": [
+    "setlist.fm",
+    "setlists",
+    "concerts",
+    "mcp"
+  ],
+  "skills": "./SKILL.md",
+  "mcp": "./.mcp.json"
+}

package/.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "setlist": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/dist/index.js"],
+      "env": {
+        "SETLIST_API_KEY": "${SETLIST_API_KEY}"
+      }
+    }
+  }
+}

package/README.md

@@ -0,0 +1,59 @@
+# setlist-mcp
+
+[![CI](https://github.com/chrischall/setlist-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/chrischall/setlist-mcp/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/setlist-mcp)](https://www.npmjs.com/package/setlist-mcp)
+
+MCP server for [setlist.fm](https://www.setlist.fm) — search concert setlists, artists, venues, tours, and cities from Claude via natural language. Read-only (setlist.fm exposes no write API).
+
+> This project was developed and is maintained by AI (Claude). Use at your own discretion.
+
+## What it does
+
+Exposes 16 read-only tools over the [setlist.fm REST API](https://api.setlist.fm/docs/1.0/index.html):
+
+| Area | Tools |
+|------|-------|
+| Artists | `setlist_search_artists`, `setlist_get_artist`, `setlist_get_artist_setlists` |
+| Setlists | `setlist_search_setlists`, `setlist_get_setlist`, `setlist_get_setlist_version` |
+| Venues | `setlist_search_venues`, `setlist_get_venue`, `setlist_get_venue_setlists` |
+| Cities & countries | `setlist_search_cities`, `setlist_get_city`, `setlist_search_countries` |
+| Users | `setlist_get_user`, `setlist_get_user_attended`, `setlist_get_user_edited` |
+| Utility | `setlist_healthcheck` |
+
+## Setup
+
+Get a free API key (non-commercial use) at [setlist.fm/settings/api](https://www.setlist.fm/settings/api), then add the server to your `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "setlist": {
+      "command": "npx",
+      "args": ["-y", "setlist-mcp"],
+      "env": {
+        "SETLIST_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+Optional: `SETLIST_ACCEPT_LANGUAGE` (one of `en, es, fr, de, pt, tr, it, pl`) localizes city/country names.
+
+See [SKILL.md](SKILL.md) for from-source setup, the full tool reference, and example flows.
+
+## Development
+
+```bash
+npm install
+npm run build   # tsc + esbuild bundle → dist/
+npm test        # vitest
+```
+
+For local runs, put `SETLIST_API_KEY=<key>` in a `.env` file (gitignored) next to the project root.
+
+See [CLAUDE.md](CLAUDE.md) for architecture, conventions, and gotchas.
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: setlist-mcp
+description: Look up concert setlists and live-music history via setlist.fm. Use when the user asks what songs an artist played at a show, their tour setlists, what was performed at a venue or on a date, or wants to find concerts by artist, venue, city, or year. Triggers on phrases like "what did Radiohead play at...", "Phish setlist for...", "shows at Red Rocks", "what songs were played on this tour", or any request about concert setlists, gigs, tours, or live performances. Requires setlist-mcp installed and the setlist server registered (see Setup below).
+---
+
+# 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](https://www.npmjs.com/package/setlist-mcp)
+- **Source:** [github.com/chrischall/setlist-mcp](https://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](https://www.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.