mcp-umphreys

A FastMCP (Streamable HTTP) MCP server for Umphrey's McGee setlist data. It reads from the umphreys-vault Postgres database (the source of truth) with a live All Things Umphreys (ATU) v2 API fallthrough for in-progress shows on show night.

No audio, no reviews: Umphrey's has no upstream analog for either.

Templated from mcp-phish; the public tool output shapes are byte-for-byte compatible with that contract so the downstream setlist game (open-setlist-stash) parses them unchanged.

Tools

Game-critical (shapes match the mcp-phish contract):

Umphrey's-native (no game dependency):

Every tool returns {"data": <model>} (or the standard {"error", "code"} failure shape) as a JSON string in the FastMCP content[0].text.

Related MCP server: Spotify MCP Server

The hot window

get_show / recent_shows for a show within VAULT_HOT_WINDOW_HOURS (default 24) of now read live from ATU instead of the vault, with a short cache TTL (HOT_WINDOW_CACHE_TTL_SECONDS, default 90s). This is required so the game's resolver sees an in-progress setlist grow on show night instead of a frozen vault snapshot. The set-label normalization (e → Encore, One Set → Set 1) is applied identically on the live and vault paths so encore detection works in both.

Running

cp .env.example .env   # set PG_PASSWORD; STUB_MODE=true skips the live network
pip install -e ".[dev]"
python -m mcp_umphreys.server   # Streamable HTTP on :3717

Tests run with no network and no Postgres (stub ATU client + a fake vault reader):

ruff check . && mypy && pytest

Deployment

docker compose up -d builds the image and joins the external umphreys-vault_default network so the server reaches the vault's postgres container by name. The opaque response cache persists in the mcp-umphreys-cache volume. Port 3717.