# King Crimson Discography MCP Server

**日本語版: [README.ja.md](README.ja.md)**
<!-- mcp-name: io.github.ytkoka/king-crimson-mcp -->
An MCP server that surfaces King Crimson record and live-performance data — including a curated **incarnation (line-up era) model** that shows how each song belongs to specific eras of the band.

## What makes this different

Generic MusicBrainz/Discogs MCP servers can already fetch releases, credits, and pressings. This server does that too, but adds two things a band-agnostic discography tool structurally can't have:

- **A cross-source integration layer keyed on MBID.** MusicBrainz, Discogs, Cover Art Archive, and setlist.fm are stitched together so one release-group MBID gets you credits, physical editions, artwork, and live history without re-resolving identities per source.
- **A King Crimson incarnation model.** King Crimson's line-up turned over almost completely, many times, over five decades — the same song can mean a totally different band depending on the year. This server hand-curates eight line-up eras and cross-references every tracked song's live-performance history against them:

  | Song | Incarnations it appears in |
  |---|---|
  | "21st Century Schizoid Man" | Spread across *every* era — the band's signature |
  | "Starless" | Only the Larks' Tongues era and the Three-drummer era |
  | "Elephant Talk" | Born in the Discipline era, gone by the Three-drummer era |

- **A local, offline-first concert cache.** Full concert history (1,200+ shows) is fetched once via `refresh_setlist_cache` and cached as JSON. Every subsequent song/tour/era query reads the cache — instant, and immune to setlist.fm's intermittent rate-limit failures during analysis.
- **Reverse lookup: song → the live albums that captured it, by era.** Ask "which live releases contain *Red*?" and get them grouped by incarnation. It cross-references two things this server already knows — when a song was played (from the setlist cache) and when each official live album was recorded (parsed from its title) — so it answers a question neither MusicBrainz nor Discogs answers directly.

  For *Red*, this surfaces 37 single-show live albums across the Discipline, THRAK, ProjeKcts and Three-drummer eras — and correctly shows **none** from the 1974 line-up that recorded it, which never played it live (numbers as of this writing; MusicBrainz's catalog can grow).

## Tools

| Tool | Description |
|---|---|
| `search_release(query, artist="King Crimson", limit=10)` | MusicBrainz album search → MBIDs |
| `get_credits(mbid, release_mbid=None)` | Per-track performer/production credits, resolved at the recording level, plus a deduplicated album roster |
| `get_editions(mbid, max_versions=25)` | Physical pressings/reissues via Discogs, preferring the exact MusicBrainz→Discogs relation over fuzzy search |
| `get_artwork(mbid)` | Cover art via the Cover Art Archive |
| `get_live_history(query="", artist="King Crimson", year=None, limit=20)` | One-page setlist.fm search by venue/city/year (no cache needed) |
| `refresh_setlist_cache(artist_mbid=<King Crimson>, max_pages=100, max_retries=3, force=False)` | Fetch and cache an artist's complete concert history from setlist.fm |
| `song_performance_history(song, artist_mbid=<King Crimson>, match="exact")` | A song's live history from the cache: `by_year`, `by_tour`, `by_incarnation` |
| `get_incarnations()` | The curated line-up eras — members, instruments, key releases |
| `refresh_live_releases_cache(artist_mbid=<King Crimson>, max_pages=10, max_retries=3, force=False)` | Fetch King Crimson's official live releases from MusicBrainz and cache them, parsing a recording date from each title |
| `song_live_releases(song, artist_mbid=<King Crimson>, match="exact")` | Find official live releases that captured a song, grouped by incarnation — matches the setlist cache against live-release recording dates |
| `refresh_box_sets_cache(discogs_artist_id=70828, artist_mbid=<King Crimson>, force=False)` | Fetch King Crimson's compilations and box sets from Discogs and cache their tracklists |
| `song_box_sets(song, artist_mbid=<King Crimson>, match="exact")` | List box sets / compilations that contain a given song (from Discogs), with year, format, Discogs URL, and occurrence count |

## The incarnation model

Eight line-up eras, split on membership changes:

| id | Era | Years |
|---|---|---|
| `kc_1969` | In the Court era | 1969 |
| `kc_1970_1972` | Transitional era | 1970 – Sep 1972 |
| `kc_1972_1974` | Larks' Tongues era | Oct 1972 – 1974 |
| `kc_1981_1984` | Discipline era | 1981 – 1984 |
| `kc_1994_1997` | Double Trio / THRAK era | 1994 – 1996 |
| `kc_1997_2003` | ProjeKcts / Nuovo Metal era | 1997 – 2003 |
| `kc_2008` | 40th Anniversary era | 2008 |
| `kc_2014_2021` | Three-drummer era | 2014 – 2021 |

Boundaries are dates, not just years — 1972 in particular splits into the Islands-era "Earthbound" spring tour (Transitional) and the Wetton-era autumn tour (Larks' Tongues), since the band's membership genuinely changed mid-year.

Line-up eras are a matter of fan interpretation, and this is one reasonable cut, not the only one. The full definition lives in `KING_CRIMSON_INCARNATIONS` in `src/king_crimson_mcp/server.py` — edit it (members, key releases, date boundaries) to match your own view; the aggregation logic doesn't need to change.

## Song → releases (reverse lookup)

"Which releases have *Red* on them?" is answered in two complementary ways, because King Crimson's live catalog splits cleanly into single-show albums and multi-show compilations.

### Single-show live albums, mapped to eras — `song_live_releases`

Needs two local caches, built once:

1. `refresh_setlist_cache` — every show and what was played (already covered above).
2. `refresh_live_releases_cache` — King Crimson's official live releases from MusicBrainz, with a recording date parsed out of each title where possible.

Both are one-time builds: the band's history is fixed, so neither cache needs to be rebuilt unless you want to pick up new MusicBrainz entries.

**How it works:** a song's performance dates come from the setlist cache; each live release carries a recording date parsed from its title (e.g. "Live in Toronto – June 24, 1974"). Where a release's recording date matches a date the song was played, that release is taken to contain the song. This is a straightforward, transparent rule — reliable for single-show live albums.

**Known limits (by design):** King Crimson has about 187 official live releases, of which only about 87 (as of this writing) have a title MusicBrainz-parseable into a full recording date — that's the range `song_live_releases` can match with confidence. The other ~100 (box sets, compilations, titles without a date) can't be matched this way; `song_live_releases` reports exactly how many were skipped in its `coverage` field rather than silently under-reporting. Excerpt compilations are an edge case too: a song played at a show can, in principle, be matched to that show's release even if the specific release is a highlights disc that omits the track — date-matching can't distinguish "recorded that night" from "included on the disc."

### Box sets & compilations, listed — `song_box_sets`

The multi-show box sets and compilations that `song_live_releases` can't date-match are covered here, from Discogs. It filters King Crimson's Discogs releases to compilations and box sets (format contains "Comp" or "Box" — which excludes single-show downloads) and lists the ones whose tracklist contains the song: title, year, format, Discogs link, and how many times the song appears on each.

**Why no era grouping here:** Discogs doesn't structure per-track recording dates, so a box set can't be split into eras the way single-show albums can. `song_box_sets` therefore *lists* the box sets containing a song rather than classifying them — era-level precision is `song_live_releases`'s job. Together they cover both halves of the question.

Needs its own one-time cache: run `refresh_box_sets_cache` (about a minute; ~38 box sets/compilations from Discogs, as of this writing). Requires `DISCOGS_TOKEN`.

For *Red*, `song_box_sets` returns 14 box sets/compilations (the "Collectors' King Crimson" volumes, "1972–1974", the "2015 Japan Tour Box", …), while `song_live_releases` handles the single-show side.

The honesty of both tools' coverage reporting is the point: results are exactly as complete as the underlying data lets them be, and you (or the calling agent) can see where to dig further instead of getting a silently incomplete answer.

## Quick start 

Three one-time steps, then it runs inside Claude.

### Step 1 — Install `uv` (one time)

`uv` is a small tool that can fetch and run this server for you.

- **macOS / Linux:**
  ```bash
  curl -LsSf https://astral.sh/uv/install.sh | sh
  ```
- **Windows (PowerShell):**
  ```powershell
  powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
  ```

Close and reopen your terminal afterward. To check it worked:
```bash
uv --version
```

### Step 2 — Get your free API keys

This server reads public music databases. Two of them need a free key:

- **setlist.fm** (live performance history) — apply for a key at
  <https://api.setlist.fm/docs/1.0/index.html>
- **Discogs** (physical editions) — create a token at
  Discogs → Settings → Developers → *Generate token*

You also set a **contact email** (`MCP_CONTACT`) — MusicBrainz requires this so
their servers know who's calling. Any email you own is fine.

(MusicBrainz and Cover Art Archive need no key.)

### Step 3 — Add it to Claude Desktop

Open Claude Desktop's config file:
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

Add this (fill in your email and keys):
```json
{
  "mcpServers": {
    "king-crimson": {
      "command": "uvx",
      "args": ["king-crimson-mcp"],
      "env": {
        "MCP_CONTACT": "you@example.com",
        "SETLISTFM_API_KEY": "your-setlistfm-key",
        "DISCOGS_TOKEN": "your-discogs-token"
      }
    }
  }
}
```
Restart Claude Desktop. King Crimson tools will appear automatically — you don't
run anything in a terminal yourself.

### Step 4 — First use

In Claude, ask something like *"Refresh the King Crimson setlist cache"* once
(it downloads the full concert history, ~40 seconds). After that, try
*"Show me the performance history of Starless"* or
*"Which incarnations played 21st Century Schizoid Man?"*

## Troubleshooting

- **"uvx: command not found" / server won't start in Claude Desktop.**
  `uv` isn't installed or isn't on your PATH. Redo Step 1, then fully quit and
  reopen Claude Desktop. On Windows you may need the full path to `uvx` in the
  `command` field.
- **A warning appears if you run it manually in a terminal.**
  Running `uvx king-crimson-mcp` directly just waits silently for a client —
  that's normal (it speaks over stdin/stdout). You don't need to run it by hand;
  Claude Desktop starts and stops it for you. Press Ctrl+C to stop.
- **`get_editions` / setlist tools return an error about a missing key.**
  That tool's API key isn't set in your config's `env` block. See Step 2.
- **setlist data looks incomplete for older tours.**
  setlist.fm is user-submitted; some historical shows or songs simply aren't
  logged there. This is a data limitation, not a bug.

## Install from PyPI

For developers — the same package as Quick start above, without the Claude Desktop config:

```bash
# run directly without installing (recommended)
uvx king-crimson-mcp

# or install as a persistent tool
pipx install king-crimson-mcp
king-crimson-mcp
```

Secrets (`MCP_CONTACT`, `DISCOGS_TOKEN`, `SETLISTFM_API_KEY`) go either in a `.env` file in the directory you run the command from, or directly in the Claude Desktop config's `env` block (see below) — either is read. `.env` is loaded from the current working directory, since an installed package has no project directory of its own to keep one in.

## Setup from source (development)

```bash
# Python 3.10+ required (3.12 recommended)
uv venv --python 3.12
source .venv/bin/activate
uv pip install -e .

# configure secrets
cp .env.example .env
# then edit .env
```

`.env` variables:

- `MCP_CONTACT` — required by MusicBrainz policy; identifies your app to their API via the User-Agent header.
- `DISCOGS_TOKEN` — needed for `get_editions` (Discogs personal access token).
- `SETLISTFM_API_KEY` — needed for `get_live_history`, `refresh_setlist_cache`, and `song_performance_history`.
- `KC_CACHE_DIR` — optional; overrides where the setlist cache is written (see below).

## Running

```bash
# quick tool check via MCP Inspector
mcp dev src/king_crimson_mcp/server.py
```

Run `refresh_setlist_cache` once first — it fetches King Crimson's full concert history (~1,200 shows, ~40 seconds) and caches it locally under `$XDG_CACHE_HOME/king-crimson-mcp` (or `~/.cache/king-crimson-mcp`; override with `KC_CACHE_DIR`) as `setlists_<artist_mbid>.json`. After that, `song_performance_history` reads from the cache and returns instantly.

Run `refresh_live_releases_cache` once as well if you want `song_live_releases` — it writes `live_releases_<artist_mbid>.json` alongside the setlist cache, in the same directory. `refresh_box_sets_cache` similarly writes `box_sets_<artist_mbid>.json` there, for `song_box_sets`.

## Register with Claude Desktop

Using the published package:

```json
{
  "mcpServers": {
    "king-crimson": {
      "command": "uvx",
      "args": ["king-crimson-mcp"],
      "env": {
        "MCP_CONTACT": "you@example.com",
        "DISCOGS_TOKEN": "...",
        "SETLISTFM_API_KEY": "..."
      }
    }
  }
}
```

Or, running from a local clone instead (after `uv pip install -e .`, which installs the same `king-crimson-mcp` console script into the venv):

```json
{
  "mcpServers": {
    "king-crimson": {
      "command": "/absolute/path/to/.venv/bin/king-crimson-mcp",
      "env": { "MCP_CONTACT": "you@example.com" }
    }
  }
}
```

Secrets can live in `.env` (in the directory the command is run from) instead of the `env` block — either is read.

## Data sources & attribution

This project is an **unofficial client** with no affiliation with or endorsement from MusicBrainz, the MetaBrainz Foundation, the Internet Archive, Discogs, or setlist.fm.

- **[MusicBrainz](https://musicbrainz.org/)** — free, no API key. Requires an identifying User-Agent with contact info (rate limit: 1 req/sec). Data is largely CC0; crediting MusicBrainz in your app is good practice. `refresh_live_releases_cache` also uses this: it lists King Crimson's official live release groups (`type=live`) — no additional service or key involved.
- **[Cover Art Archive](https://coverartarchive.org/)** — a joint MusicBrainz / Internet Archive project. Images are contributed by individual uploaders; follow the same attribution etiquette as MusicBrainz.
- **[Discogs](https://www.discogs.com/developers)** — requires a personal access token and a unique User-Agent (60 req/min authenticated). Use is subject to the Discogs API terms of service. `song_box_sets` uses the same Discogs API as `get_editions` (no additional service or key).
- **[setlist.fm](https://api.setlist.fm/docs/1.0/index.html)** — requires an API key (apply at api.setlist.fm). **Any display of setlist.fm data must include an attribution link to the source setlist** — every performance returned by this server includes its `url` for exactly that purpose; surface it wherever you show the data. setlist.fm data is user-submitted, so completeness and accuracy are not guaranteed.

## Limitations

- setlist.fm data is user-submitted — some shows or songs may be missing or incorrect, especially from older tours.
- The incarnation boundaries are one interpretation of King Crimson's line-up history, not an official taxonomy.
- Performer credits depend on what MusicBrainz has cataloged for a given release; sparser releases yield sparser credits.
- `song_live_releases` can only match live releases whose title yields a full recording date (about half of King Crimson's ~187 official live releases); see [Song → releases](#song--releases-reverse-lookup) above for what's out of reach and why.
- `song_box_sets` can't classify box sets by incarnation — Discogs doesn't structure per-track recording dates, so it lists matching box sets/compilations rather than era-grouping them. A handful of the ~38 compilations it scans are multi-artist collections where King Crimson contributed only one track; these can surface as noise for very common song titles.

## License

MIT — see [LICENSE](LICENSE).