mcp-phish

api.phish.net v5およびphish.in v2 APIを単一の型付きツールインターフェースでラップするMCPサーバーです。 セットリスト、楽曲、ジャムチャート、レビュー、オーディオにわたる12種類のツールを提供します。すべてのレスポンスは固定されたPydanticモデルを通じて整形されるため、上流のAPI変更があってもワイヤフォーマットは安定して維持されます。

FastMCPとStreamable HTTPトランスポート上に構築されています。信頼できるLAN内やTailscale ACLの背後で実行するように設計されており、MCPレベルの認証は組み込まれていません。

なぜこれが必要か

現在、Phish.netとphish.inのエコシステムは、メンテナンスされていないラッパーや場当たり的なスクリプトの小さな集合体に過ぎません。これらをきれいに統合しているものはありません。mcp-phishは、MCP対応クライアント（Claude Code、Claude Desktop、カスタムエージェントなど）に対し、ファンが実際に尋ねる質問（特定の日付のセットリスト、楽曲の初演とギャップ、トラックのオーディオURL、ツアーのジャムチャートヒットなど）に対して、焦点を絞った適切に型付けされたインターフェースを提供します。

ソースは変更される可能性があります（ライブAPI → キャッシュ → ボールト）。しかし、MCPクライアントに返されるPydanticの形状は決して変わりません。

クイックスタート

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

サーバーはデフォルトでスタブモードで起動します。現実的なモックデータを返し、ネットワークアクセスやAPIキーは不要です。Claude Codeに登録します：

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

次にClaudeにこう尋ねてください："What was the setlist on 12/30/95?"。すると、Madison Square Gardenでの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

ツールリファレンス

すべてのツールは、標準的なエンベロープを持つ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"で固定されているため、上流の変更は黙って形状が変わるのではなく、バリデーションエラーとなります。

スタブモードとリアルモード

モードの切り替えは設定変更であり、コード変更ではありません。同じ12種類のツール、同じレスポンス形状です。

キャッシュ

mcp-phishは、ディスク上（/data/phish-cache.db, aiosqlite）に(endpoint, params_hash)をキーとする不透明なキーバリューストアを保持します。すべてのエントリには単一のTTL（CACHE_TTL_SECONDS、デフォルトは86400 = 24時間）が適用されます。ヒットした場合は、上流への呼び出しは行われません。

このキャッシュは正規化されたデータストアではありません。上流のレート制限を回避し、LLMによる繰り返し探索を高速化するために、生のJSONレスポンスを保持しているだけです。一時的なものとして扱ってください。

スロットリング

すべての上流呼び出しは、設定可能な定常レートを持つインスタンスごとのトークンバケットを通過します：

バケットはプロセス内で行われます。複数のコンテナ間で調整は行われません。トークンの状態はhealth()で公開されるため、Claude Codeセッションから残量を確認できます。

設定

すべての設定は環境変数（および存在する場合は.envファイル）から読み込まれます。Pydanticが起動時にバリデーションを行い、無効な値がある場合は即座に失敗します。

完全な例は.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形状に投影します。キャッシュ以外の状態は保持しません。2つのPhish API以外のクラウドサービスは呼び出しません。

セキュリティ上の注意

• mcp-phishは、信頼できるLAN、Tailscale上、または認証付きのリバースプロキシの背後で実行してください。サーバー自体はMCPクライアントを認証しません。

• APIキーはコンテナの環境変数内にのみ存在します。ログに記録されたり、レスポンスにエコーされたり、ディスクに書き込まれたりすることはありません。

• コンテナはUID 1000で実行され、シェルやホームディレクトリはなく、読み取り専用のルートファイルシステム（/tmpはtmpfs）で、no-new-privilegesが設定されています。

• /dataキャッシュボリュームのみが書き込み可能なパスです。

• Pythonの依存関係は、ハッシュロックされたrequirements.lockからpip --require-hashesでインストールされます。ベースイメージは最初のタグ付きリリース前にダイジェストで固定されます。

• 公開されるイメージはマルチアーキテクチャ（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データプロジェクトのフェーズ1です。上記で文書化されたPydanticコントラクトは、将来のフェーズでもバイト単位で同一に保たれます。

• フェーズ2 — Postgresボールト + 夜間ETLハイドレーション。

• フェーズ3 — このMCPのためのボールトバックエンドの読み取りパス。ホットウィンドウは直近の公演をライブで読み取り、古いものはボールトから読み取ります。

• フェーズ4 — セットリスト予測ゲーム（別リポジトリ）。

• フェーズ5 — MCP上のチャット + ダッシュボードUI（別リポジトリ）。

フェーズのステータスはhttps://github.com/pete-builds/mcp-phish/issuesで確認できます。

謝辞

コーパスを公開し、機械可読な状態に保ってくれているphish.netおよびphish.inの運営者に感謝します。このラッパーはどちらのプロジェクトとも提携していません。彼らのレート制限と利用規約を尊重してください。

ライセンス

MIT。

貢献

Issueやプルリクエストを歓迎します。PRを作成する前に：

1. ruff check, ruff format --check, mypy src/mcp_phishがクリーンであることを確認してください。

2. テストを追加または更新し、カバレッジを80%以上に保ってください。

3. ローカルでpytestを実行し、スイートがパスすることを確認してください。

4. CHANGELOG.mdの[Unreleased]見出しの下を更新してください。