Phish

CI License: MIT Python MCP

An MCP server that wraps the api.phish.net v5 and phish.in v2 APIs behind a single typed tool surface. Sixteen tools across setlists, songs, jam-charts, reviews, audio, venues, and catalog statistics. Every response is shaped through frozen Pydantic models so the wire format stays stable across upstream API drift.

Built on FastMCP with Streamable HTTP transport. Designed to run on a trusted LAN or behind a Tailscale ACL — there is no built-in MCP-level auth.

Why

Today the Phish.net + phish.in ecosystem is a small set of unmaintained wrappers and one-off scripts. Nobody combines the two cleanly. mcp-phish gives any MCP-aware client (Claude Code, Claude Desktop, custom agents) a focused, well-typed surface area for the questions phans actually ask: setlist for a date, song debut and gap, audio URL for a track, jam-chart hits for a tour.

Source can change (live API → cached → vault). The Pydantic shapes returned to MCP clients never do.

Quick start

docker run --rm \
  -p 3705:3705 \
  -e STUB_MODE=true \
  ghcr.io/pete-builds/mcp-phish:latest

The server starts in stub mode by default. It returns realistic mock data and requires no network access or API key. Register it with Claude Code:

claude mcp add phish --transport http --scope user --url http://localhost:3705/mcp

Then ask Claude: "What was the setlist on 12/30/95?" and you should get back Madison Square Garden with the Mike's > Simple > Weekapaug groove.

To talk to the real APIs, register a free key at api.phish.net/keys/ and flip stub mode off:

docker run --rm \
  -p 3705:3705 \
  -e STUB_MODE=false \
  -e PHISHNET_API_KEY=<your-key> \
  ghcr.io/pete-builds/mcp-phish:latest

Tool reference

Source column reads: vault → API means the tool prefers the Postgres vault and falls through to the live API inside the hot window (or when the vault is disabled). vault only means the tool has no upstream equivalent and returns VAULT_DISABLED when the vault is off. See Vault read path.

Tool	Source	What it does
search_shows	vault → phish.net	Search shows by year + venue + city/state/country.
get_show	vault → phish.net	Full show: setlist, ratings, reviews count, venue.
recent_shows	vault → phish.net	N most recent shows, most-recent-first.
search_songs	vault → phish.net	Search the song catalog by title fragment or community nickname. Surfaces current gap.
get_song	vault → phish.net	One song record: debut, last play, gap, total.
validate_song_slugs	vault → phish.net	Partition 1-50 candidate slugs into valid and unknown. One round-trip on vault.
song_history	vault → phish.net	Every performance of a song, most-recent-first.
jam_chart	vault → phish.net	Editorially flagged notable jams.
get_reviews	vault → phish.net	User reviews for a show.
get_audio	vault → phish.in	Track list + MP3 URLs + durations for a show.
get_track	vault → phish.in	One audio track by id.
search_audio_tracks	vault → phish.in	Every recorded version of one song slug.
venue_history	vault only	All shows at a venue, most recent first.
songs_by_gap	vault only	Songs ranked by current gap, descending. Bust-out candidates.
stats_overview	vault only	Catalog-wide roll-up: totals, most-played, biggest gaps, rarest, recent debuts, longest shows.
health	meta	Server status, throttle state, cache stats, vault freshness.

Every tool returns a JSON string with the standard envelope:

{"data": <typed payload>}

or, on failure:

{
  "error": "human-readable message",
  "code": "UPSTREAM_DOWN | NOT_FOUND | INVALID_INPUT | RATE_LIMITED | INTERNAL",
  "details": { "...": "..." }
}

The Pydantic models in src/mcp_phish/models.py (Venue, ShowSummary, Show, SetlistEntry, SongSummary, Song, Performance, NotableJam, Review, Track, ShowAudio, VenueShow, SongGap, SlugValidation, TopSong, DebutSong, LongShow, StatsOverview, Health) are the public contract. They are frozen with extra="forbid" so any upstream drift becomes a validation error rather than a silent shape change.

Stub mode vs real mode

Mode	When to use	Behavior
Stub (STUB_MODE=true, default)	Development, demos, no API key yet	Realistic mock payloads for a small set of canonical shows (12/30/95 MSG, 11/17/97 Denver, 12/31/24 MSG). Every API-backed tool returns the same Pydantic shape it would in real mode.
Real (STUB_MODE=false)	Production with a phish.net API key	Talks HTTPS to api.phish.net v5 and phish.in v2. Requires PHISHNET_API_KEY; PHISHIN_API_KEY is optional.

Switching modes is a config change, not a code change. Same sixteen tools, same response shapes.

STUB_MODE and VAULT_ENABLED are independent switches. Stub mode only governs the two upstream HTTP clients; it does not stand in for the vault. The three vault-only tools (venue_history, songs_by_gap, stats_overview) return VAULT_DISABLED whenever VAULT_ENABLED=false, in stub mode and real mode alike.

Vault read path

Reads are served from a phish-vault Postgres database when VAULT_ENABLED=true, with a live-API fallthrough for shows inside the hot window. This is implemented and in production, not planned.

How a read resolves:

1. Vault disabled (VAULT_ENABLED=false, the default) — every tool goes straight to the upstream API exactly as it did before the vault existed. Vault-only tools return VAULT_DISABLED.
2. Vault enabled, show outside the hot window — served from Postgres. No upstream call.
3. Vault enabled, show inside the hot window — a setlist is typed into phish.net live during and just after a show, so recent dates bypass the vault and read the API under a short cache TTL (HOT_WINDOW_CACHE_TTL_SECONDS) so repeat polls see fresh setlists. The window is anchored to the end of the show day in US/Eastern, not midnight UTC, and spans VAULT_HOT_WINDOW_HOURS.
4. Vault enabled but stale — if the last successful ETL run is older than VAULT_MAX_STALE_HOURS, health() reports vault.stale: true and an overall status of degraded. Note this is a reporting signal only: read tools keep serving vault rows regardless of staleness. Monitor health() if stale data matters to your client.

Vault rows and API payloads project through separate mappers into the same frozen Pydantic models, so the wire format does not tell a client which source answered. health() reports vault connectivity and ETL freshness when you need to know.

Caching

mcp-phish keeps an opaque key-value cache on disk (/data/phish-cache.db, aiosqlite) keyed by (endpoint, params_hash). A single TTL governs every entry (CACHE_TTL_SECONDS, default 86400 = 24h). On a hit, no upstream call is made.

This cache is not a normalized data store. It just holds raw JSON responses to keep us under the upstream rate limits and to make repeated LLM-driven exploration fast. Treat it as ephemeral.

Throttling

Every upstream call passes through a per-instance token bucket with a configurable steady-state rate:

Variable	Default	Notes
THROTTLE_PHISHNET_RPS	5	api.phish.net v5 requests per second.
THROTTLE_PHISHIN_RPS	10	phish.in v2 requests per second.

The bucket is in-process. Multiple containers do not coordinate. Token state is exposed in health() so a Claude Code session can see what's left.

Configuration

All configuration is read from environment variables (and a .env file when present). Pydantic validates at startup and fails fast on invalid values.

Variable	Type	Default	Required	Notes
STUB_MODE	bool	true	no	When false, real-mode credentials are required.
PHISHNET_API_KEY	string	""	only in real mode	Free at api.phish.net/keys/.
PHISHIN_API_KEY	string	""	no	Optional; raises rate caps.
PHISHNET_BASE_URL	string	https://api.phish.net/v5	no	Override for testing.
PHISHIN_BASE_URL	string	https://phish.in/api/v2	no	Override for testing.
CACHE_DB_PATH	string	/data/phish-cache.db	no	aiosqlite file path.
CACHE_TTL_SECONDS	int	86400	no	24h default.
HOT_WINDOW_CACHE_TTL_SECONDS	int	see config.py	no	Short TTL applied to live reads inside the hot window so polls see fresh setlists.
THROTTLE_PHISHNET_RPS	float	5.0	no	Per-second steady rate.
THROTTLE_PHISHIN_RPS	float	10.0	no	Per-second steady rate.
VAULT_ENABLED	bool	false	no	When true, read tools prefer the Postgres vault. See Vault read path.
VAULT_HOT_WINDOW_HOURS	int	see config.py	no	Hours after end-of-show-day (ET) during which reads bypass the vault and go live.
VAULT_MAX_STALE_HOURS	int	see config.py	no	ETL age past which health() reports the vault stale/degraded. Reporting only; does not gate reads.
PG_HOST	string	postgres	only when vault enabled	phish-vault Postgres host.
PG_PORT	int	5432	no	Postgres port.
PG_DB	string	phish	no	Vault database name.
PG_USER	string	phish	no	Vault role.
PG_PASSWORD	secret	""	only when vault enabled	Never logged; omitted from health().
MCP_HOST	string	0.0.0.0	no	Bind address.
MCP_PORT	int	3705	no	Listen port.
LOG_LEVEL	enum	INFO	no	One of DEBUG, INFO, WARNING, ERROR, CRITICAL.
LOG_FORMAT	enum	json	no	json for production, text for local dev.

A complete example lives in .env.example.

MCP client setup

Claude Code

claude mcp add phish --transport http --scope user --url http://<host>:3705/mcp

Claude Desktop

{
  "mcpServers": {
    "phish": {
      "transport": "streamable-http",
      "url": "http://<host>:3705/mcp"
    }
  }
}

Generic config

Streamable HTTP at http://<host>:3705/mcp. Any MCP client supporting the Streamable HTTP transport can connect.

Architecture

+---------------------+     Streamable HTTP     +---------------------+
|  MCP Client         |  -------------------->  |  mcp-phish          |
|  (Claude Code, etc) |  <--------------------  |  (FastMCP server)   |
+---------------------+                         +----------+----------+
                                                           |
                                        VAULT_ENABLED?     |
                            +------------------------------+
                            |                              |
                   true, outside hot window        false, or inside
                            |                        hot window
                            v                              |
                 +----------+----------+                   v
                 |  phish-vault        |        +----------+----------+
                 |  Postgres           |        | aiosqlite KV cache  |
                 |  (nightly ETL)      |        |  /data/phish-cache  |
                 +---------------------+        +----------+----------+
                                                           | miss
                                                           v
                                            +--------------+--+   +----------------+
                                            | api.phish.net v5 |   | phish.in/api/v2|
                                            +------------------+   +----------------+

mcp-phish is an async read proxy over two sources. With the vault disabled it is a thin API proxy with a small cache: it translates MCP tool calls into upstream REST calls, caches raw responses for the configured TTL, and projects them into the public Pydantic shape. With the vault enabled it reads phish-vault Postgres for everything outside the hot window and falls through to the same API path for recent shows.

Either way mcp-phish owns no durable state of its own beyond the KV cache: the vault is a separate service hydrated by its own nightly ETL, and mcp-phish only ever reads from it (vault.py issues SELECT and nothing else). Grant the PG_USER role read-only privileges to enforce that at the database, too. It calls no cloud services other than the two phish APIs.

Security notes

• Run mcp-phish on a trusted LAN, on Tailscale, or behind a reverse proxy with auth. The server itself does not authenticate MCP clients.
• API keys live only in the container's environment. They are never logged, never echoed in responses, and never written to disk.
• The container runs as UID 1000, no shell, no home directory, with a read-only root filesystem (/tmp is tmpfs) and no-new-privileges.
• The /data cache volume is the only writable path.
• Python deps install with pip --require-hashes from a hash-locked requirements.lock. Both Dockerfile stages pin the base image by digest, refreshed by Dependabot.
• Published images are multi-arch (amd64/arm64) with build provenance and SBOM via docker/build-push-action.

For vulnerability reports, see SECURITY.md.

Development

Requires Python 3.13+ and Docker.

# Clone + install dev deps
git clone https://github.com/pete-builds/mcp-phish.git
cd mcp-phish
python -m venv .venv && source .venv/bin/activate
pip install --require-hashes -r requirements-dev.lock
pip install -e . --no-deps

# Run the test suite
pytest

# Lint and format
ruff check src tests
ruff format src tests

# Type check (mypy strict)
mypy src/mcp_phish

# Run the server locally in stub mode
python -m mcp_phish.server

# Or build the image yourself
cp docker-compose.example.yml docker-compose.yml
docker compose up --build

Updating dependencies

The requirements.lock and requirements-dev.lock files are hash-pinned. Edit the matching .in file then regenerate:

uv pip compile requirements.in --output-file requirements.lock --generate-hashes --python-version 3.13
uv pip compile requirements-dev.in --output-file requirements-dev.lock --generate-hashes --python-version 3.13

Dependabot opens weekly PRs for requirements.in-level updates, the Docker base image, and GitHub Actions versions.

Roadmap

This server is part of a larger Phish data project. The Pydantic contract documented above stays byte-identical across phases.

• Phase 1 — done. Typed MCP surface over the phish.net and phish.in APIs, with an aiosqlite response cache and per-upstream throttling.
• Phase 2 — done (separate repo). Postgres vault + nightly ETL hydration.
• Phase 3 — done. Vault-backed read path for this MCP, with hot-window fallthrough so recent shows read live and older reads come from the vault. All sixteen tools consult the vault when VAULT_ENABLED=true; three of them (venue_history, songs_by_gap, stats_overview) are vault-only. See Vault read path for the resolution order and Configuration for the VAULT_* / PG_* variables.
• Phase 4 — in progress (separate repo). Setlist-prediction game.
• Phase 5 — planned (separate repo). Chat + dashboard UI over MCP.

Phase status lives at https://github.com/pete-builds/mcp-phish/issues.

Acknowledgments

Thanks to the phish.net and phish.in operators for keeping the corpus public and machine-accessible. This wrapper is unaffiliated with either project. Please respect their rate limits and terms of service.

License

MIT.

Contributing

Issues and pull requests welcome. Before opening a PR:

1. Make sure ruff check, ruff format --check, and mypy src/mcp_phish are clean.
2. Add or update tests; keep coverage at 80% or above.
3. Run pytest locally and confirm the suite passes.
4. Update CHANGELOG.md under an [Unreleased] heading.