Skip to main content
Glama
deenesjakoruzh
pete-builds

mcp-phish

by pete-builds
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

mcp-phish

CI License: MIT Python MCP

一个 MCP 服务器，它将 api.phish.net v5 和 phish.in v2 API 封装在统一的类型化工具界面之下。涵盖歌单、歌曲、即兴演奏图表、评论和音频的十二个工具。每个响应都通过冻结的 Pydantic 模型进行塑形，以确保在下游 API 发生变动时，线路格式保持稳定。

基于 FastMCP 和 Streamable HTTP 传输构建。专为在受信任的局域网或 Tailscale ACL 后运行而设计 — 没有内置的 MCP 级别身份验证。

为什么

目前 Phish.net + phish.in 生态系统由少量无人维护的封装器和一次性脚本组成。没有人能干净地将两者结合起来。mcp-phish 为任何支持 MCP 的客户端（Claude Code、Claude Desktop、自定义代理）提供了一个专注且类型良好的界面，用于回答 Phish 粉丝真正关心的问题：特定日期的歌单、歌曲首演和间隔、曲目的音频 URL、巡演的即兴演奏图表热门曲目。

数据源可能会变（实时 API → 缓存 → 仓库）。但返回给 MCP 客户端的 Pydantic 形状永远不会变。

Related MCP server: mcp-umphreys

快速入门

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

服务器默认以 存根模式 (stub mode) 启动。它返回真实的模拟数据，不需要网络访问或 API 密钥。将其注册到 Claude Code：

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

然后询问 Claude：“12/30/95 的歌单是什么？”，你应该会得到麦迪逊广场花园的演出信息，包含 Mike's > Simple > Weekapaug 的律动。

要连接到真实的 API，请在 api.phish.net/keys/ 注册一个免费密钥并关闭存根模式：

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

工具参考

工具

数据源

功能

search_shows

phish.net

按年份 + 场地 + 城市/州/国家搜索演出。

get_show

phish.net

完整演出：歌单、评分、评论数、场地。

recent_shows

phish.net

最近的 N 场演出，按时间倒序排列。

search_songs

phish.net

按标题片段搜索歌曲目录。

get_song

phish.net

单个歌曲记录：首演、最后演奏、间隔、总数。

song_history

phish.net

歌曲的每一次表演，按时间倒序排列。

jam_chart

phish.net

编辑精选的著名即兴演奏。

get_reviews

phish.net

演出的用户评论。

get_audio

phish.in

演出的曲目列表 + MP3 URL + 时长。

get_track

phish.in

按 ID 获取单个音频曲目。

search_audio_tracks

phish.in

单首歌曲的所有录音版本。

health

meta

服务器状态、限流状态、缓存统计。

每个工具都返回一个带有标准信封的 JSON 字符串：

{"data": <typed payload>}

或者，在失败时：

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

src/mcp_phish/models.py 中的 Pydantic 模型（ShowSummary, Show, SetlistEntry, Song, Performance, NotableJam, Review, Track, ShowAudio, Health）是公共契约。它们使用 extra="forbid" 进行了冻结，因此任何上游变动都会变成验证错误，而不是静默的形状更改。

存根模式 vs 真实模式

模式

使用场景

行为

存根 (STUB_MODE=true, 默认)

开发、演示、暂无 API 密钥

为少量经典演出（12/30/95 MSG, 11/17/97 Denver, 12/31/24 MSG）提供真实的模拟负载。每个工具返回与真实模式相同的 Pydantic 形状。

真实 (STUB_MODE=false)

生产环境，拥有 phish.net API 密钥

通过 HTTPS 与 api.phish.net v5 和 phish.in v2 通信。需要 PHISHNET_API_KEY；PHISHIN_API_KEY 为可选。

切换模式是配置更改，而非代码更改。相同的十二个工具，相同的响应形状。

缓存

mcp-phish 在磁盘上保留一个不透明的键值缓存 (/data/phish-cache.db, aiosqlite)，键为 (endpoint, params_hash)。单个 TTL 控制每个条目（CACHE_TTL_SECONDS，默认 86400 = 24小时）。命中缓存时，不会进行上游调用。

此缓存不是规范化的数据存储。它仅保存原始 JSON 响应，以保持在上游速率限制内，并使重复的 LLM 驱动探索变得快速。将其视为临时数据。

限流

每个上游调用都通过一个具有可配置稳态速率的实例内令牌桶：

变量

默认值

说明

THROTTLE_PHISHNET_RPS

5

api.phish.net v5 每秒请求数。

THROTTLE_PHISHIN_RPS

10

phish.in v2 每秒请求数。

令牌桶是进程内的。多个容器不会协调。令牌状态在 health() 中公开，以便 Claude Code 会话可以查看剩余额度。

配置

所有配置均从环境变量（以及存在时的 .env 文件）读取。Pydantic 在启动时进行验证，并在值无效时快速失败。

变量

类型

默认值

必需

说明

STUB_MODE

bool

true

否

为 false 时，需要真实模式凭据。

PHISHNET_API_KEY

string

""

仅在真实模式

在 api.phish.net/keys/ 免费获取。

PHISHIN_API_KEY

string

""

否

可选；提高速率上限。

PHISHNET_BASE_URL

string

https://api.phish.net/v5

否

测试覆盖。

PHISHIN_BASE_URL

string

https://phish.in/api/v2

否

测试覆盖。

CACHE_DB_PATH

string

/data/phish-cache.db

否

aiosqlite 文件路径。

CACHE_TTL_SECONDS

int

86400

否

默认 24 小时。

THROTTLE_PHISHNET_RPS

float

5.0

否

每秒稳态速率。

THROTTLE_PHISHIN_RPS

float

10.0

否

每秒稳态速率。

MCP_HOST

string

0.0.0.0

否

绑定地址。

MCP_PORT

int

3705

否

监听端口。

LOG_LEVEL

enum

INFO

否

DEBUG, INFO, WARNING, ERROR, CRITICAL 之一。

LOG_FORMAT

enum

json

否

生产环境用 json，本地开发用 text。

完整示例位于 .env.example。

MCP 客户端设置

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"
    }
  }
}

通用配置

在 http://<host>:3705/mcp 上的 Streamable HTTP。任何支持 Streamable HTTP 传输 的 MCP 客户端都可以连接。

架构

+---------------------+     Streamable HTTP     +---------------------+
|  MCP Client         |  -------------------->  |  mcp-phish          |
|  (Claude Code, etc) |  <--------------------  |  (FastMCP server)   |
+---------------------+                         +----+--------------+-+
                                                     |              |
                                                     |              |
                                                     v              v
                                          +----------+--+   +-------+--------+
                                          | api.phish.net|   | phish.in/api/v2|
                                          |     v5       |   |                |
                                          +--------------+   +----------------+

                                                     ^
                                                     |
                                          +----------+----------+
                                          | aiosqlite KV cache  |
                                          |  /data/phish-cache  |
                                          +---------------------+

mcp-phish 是一个带有小型缓存的轻量级异步代理：它将 MCP 工具调用转换为上游 REST 调用，为配置的 TTL 缓存原始响应，并将它们投影到公共 Pydantic 形状中。除了该缓存外，它不存储任何状态。除了两个 Phish API 外，它不调用任何云服务。

安全说明

  • 在受信任的局域网、Tailscale 上或在带有身份验证的反向代理后运行 mcp-phish。服务器本身不对 MCP 客户端进行身份验证。

  • API 密钥仅存在于容器的环境中。它们永远不会被记录、永远不会在响应中回显，也永远不会写入磁盘。

  • 容器以 UID 1000 运行，无 shell，无主目录，具有 只读根文件系统 (/tmp 为 tmpfs) 和 no-new-privileges。

  • /data 缓存卷是唯一可写的路径。

  • Python 依赖项使用 pip --require-hashes 从哈希锁定的 requirements.lock 安装。基础镜像将在第一个标记版本发布前按摘要固定。

  • 发布的镜像是多架构 (amd64/arm64) 的，具有构建来源和通过 docker/build-push-action 生成的 SBOM。

有关漏洞报告，请参阅 SECURITY.md。

开发

需要 Python 3.13+ 和 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

更新依赖项

requirements.lock 和 requirements-dev.lock 文件是哈希锁定的。编辑匹配的 .in 文件然后重新生成：

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 每周为 requirements.in 级别的更新、Docker 基础镜像和 GitHub Actions 版本打开 PR。

路线图

此服务器是更大规模 Phish 数据项目的 第一阶段。上述记录的 Pydantic 契约在未来的阶段中将保持字节一致。

  • 第二阶段 — Postgres 仓库 + 每晚 ETL 水合。

  • 第三阶段 — 此 MCP 的仓库支持读取路径。热窗口穿透读取最近的演出直播；旧数据从仓库读取。

  • 第四阶段 — 歌单预测游戏（独立仓库）。

  • 第五阶段 — 基于 MCP 的聊天 + 仪表板 UI（独立仓库）。

阶段状态位于 https://github.com/pete-builds/mcp-phish/issues。

致谢

感谢 phish.net 和 phish.in 的运营者保持语料库公开且可被机器访问。此封装器与这两个项目均无关联。请尊重他们的速率限制和服务条款。

许可证

MIT。

贡献

欢迎提交问题和拉取请求。在打开 PR 之前：

  1. 确保 ruff check, ruff format --check 和 mypy src/mcp_phish 是干净的。

  2. 添加或更新测试；保持覆盖率在 80% 或以上。

  3. 在本地运行 pytest 并确认套件通过。

  4. 在 [Unreleased] 标题下更新 CHANGELOG.md。

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityActive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • setlist-mcp

    chrischall
    A
    license
    A
    quality
    A
    maintenance
    Search concert setlists, artists, venues, tours, and cities from setlist.fm via natural language. Provides 16 read-only tools for exploring live music data.
    20
    749 npm
    1
    MIT

  • mcp-umphreys

    pete-builds
    A
    license
    Not graded
    quality
    A
    maintenance
    Enables querying Umphrey's McGee setlist data including shows, songs, jam charts, and guest appearances through natural language.
    MIT

  • Foursquare MCP Server

    jbeker
    F
    license
    A
    quality
    D
    maintenance
    Exposes Foursquare/Swarm check-in data and user activity through 13 tools, enabling user management, check-in history, venue details, mayorships, lists, and cross-user search.
    13
    -

  • listenbrainz-mcp

    Dthen
    A
    license
    A
    quality
    C
    maintenance
    Enables interaction with the full public ListenBrainz API, exposing 37 tools for listens, stats, playlists, radio, social, and cover art over stdio.
    37
    BSD Zero Clause