mcp-phish

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.

Related MCP server: mcp-umphreys

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.

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

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:

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.

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.