stathead-mcp

stathead-mcp

StatHead の NFL ファンタジー分析ツールセットを Claude（Desktop / Code）、Cursor、または任意の MCP クライアントに提供する MCP サーバーです。自然言語で質問すると、最新の構造化された NFL データを取得できます。

ランタイム依存関係のない自己完結型の単一バンドルとして提供され、必要に応じてすべてのデータを取得するため、ダウンロードやビルドは不要です。npx で実行できます。

利用できる機能

選手やチームのデータを網羅する 50 のツールを利用できます。

分野	ツール
データの確認	get_metadata — データソース、シーズンの対象範囲、有効な列挙値（質問の範囲を決めるため、最初に呼び出してください）
選手	シーズン統計、週別／試合別ログ、スナップ数、負傷情報、高度な統計、Next Gen Stats、ロスター、契約、get_depth_charts（ロスターの状況、StatHead のデプス順、移籍情報を表示する view=changes に対応した、ポジション枠を考慮したチームのデプスチャート）
試合とプレー	日程／結果、プレーごとの記録、出場状況、FTN のチャートデータ
ファンタジー	StatHead の複合型ダイナスティ評価値、get_trade_values（完了した数百万件の Sleeper ダイナスティトレードに基づいて算出した StatHead 評価値：90％範囲付きの週次時点別評価値、変動選手、流動性、スコアリング方式に応じた再評価、1／3／6／12 か月予測、ルーキーピックのクラスと履歴）、get_projections（StatHead 独自のシーズン PPG モデル）、get_weekly_projections（第 1～18 週の週別対戦相手補正済みポイント）、get_matchups（対戦相手の週別強度：各ディフェンスが QB／RB／WR／TE に許す試合あたりのファンタジーポイントを、指定したスコアリング方式と期待値比で 1～32 位にランク付け。週別、選手別、残りの日程別、または TE のレシーブ数や QB のラッシングなどの指標別に表示）、ADP（FFC / ESPN / Sleeper）、get_adp_with_results（ADP と実際の順位の比較）、追加／削除のトレンド
Sleeper リーグ	get_sleeper_user_leagues、get_sleeper_league（順位表＋ロスター）、get_sleeper_league_users（効率よくマネージャー一覧を取得）、get_sleeper_matchups、get_sleeper_transactions（トレード／ウェイバー／追加）、get_sleeper_waiver_wire（フリーエージェント × トレンド × 予測値）、get_sleeper_draft、get_sleeper_user_snooper（複数リーグにまたがる保有状況）、get_sleeper_user_history（複数シーズンの成績＋優勝タイトル） — これらを連携したグラフとして利用できます。ユーザー名からリーグ一覧を取得し、リーグ名（または ID）からそのリーグを開けます。各マネージャーの owner_id／表示名をたどることで、そのマネージャー のリーグ、保有状況、履歴を確認できます
ドラフトと大学	get_prospect_outcomes（調整済みの成功／失敗確率＋評価）、ドラフト指名、get_rookie_class（ドラフト＋コンバイン＋ルーキー統計を一度の呼び出しで取得）、プロスペクトのプロフィール、コンバイン、大学統計（選手別または選手グループ別）、QBR
モデルと方法論	get_model_docs（モデルの仕組み＋ポジション別の特徴量重要度）、get_player_features（選手がその評価になった理由 — 評価を左右する特徴量、範囲、方向）
独自の数値	export_excel / import_excel / clear_overrides — スタイル付きの予測値／ランキング／ルーキーランキングのワークブックをダウンロードする（または PPR の数式がその場で反映される by_team 予測シートをダウンロードする）、編集して再アップロードすることで、その後のすべてのクエリに自分の数値を反映できます

独自の予測値とランキングを使う

ウェブサイトからダウンロードできるものと同じ一覧を、MCP 経由で通常の .xlsx ファイルとして利用できます（追加の依存関係は不要で、Node 標準の zlib を使用します）。

1. export_excel kind="projections"（または rankings、rookie_rankings）を実行すると、スタイル付きのワークブックがディスクに保存され、パスが返されます。Excel または Google Sheets で、ハイライトされた列（予測値の場合は Proj PPG、ランキング／ルーキーの場合は My Rank）を編集します。
2. import_excel path="…" でファイルを読み込み、編集した数値をオーバーライドとして保存します。
3. 以降、get_projections、get_fantasy_rankings、get_prospect_outcomes は clear_overrides を実行するまで、あなたの数値を自動的に使用します（出力にもその旨が表示されます）。

ワークブックの保存先はデフォルトで $STATHEAD_DIR（または現在の作業ディレクトリ）です。保存先を指定するには path を渡してください。オーバーライドは $STATHEAD_DIR/~/.stathead/overrides.json に保存されます。

クイックスタート

インストールもクローンも不要で、そのまま実行できます。

npx -y stathead-mcp

stdio 経由で MCP と通信するため、通常は手動で実行するのではなく、クライアントに接続して使います。

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）に追加します。

{
  "mcpServers": {
    "stathead": {
      "command": "npx",
      "args": ["-y", "stathead-mcp"]
    }
  }
}

Claude Code

claude mcp add stathead -- npx -y stathead-mcp

Cursor ／その他の MCP クライアント

クライアントの MCP 設定で、同じ command／args（npx -y stathead-mcp）を使用します。

Claude モバイルアプリ／claude.ai ウェブ／Claude Desktop（リモートコネクター）

ローカルコマンドではなく URL を使いたい場合、同じツールを Cloudflare Worker（workers/stathead-mcp/、deploy-workers.yml 経由でデプロイ）によって、MCP の Streamable HTTP トランスポートで提供しています。

https://stathead-mcp.dachhack.workers.dev

Settings → Connectors → Add custom connector から追加し、URL を貼り付けて保存します。コマンドも API キーも不要です。（この URL への GET は簡単なヘルスチェック情報を返し、クライアントは JSON-RPC を POST します。）上記の npm／stdio パッケージは、引き続き Claude Code と Cursor で利用できます。

Worker は、プライバシーに配慮した使用状況カウンターを記録します（MCP メソッドとツール名のみ。IP アドレスやリクエスト本文は記録しません）。記録先は Cloudflare Analytics Engine のデータセット（stathead_mcp_usage）です。Worker シークレット（wrangler secret put …）に CF_ACCOUNT_ID と CF_ANALYTICS_TOKEN を設定すると、GET /stats で集計を確認できます。または、Cloudflare ダッシュボードでデータセットをクエリできます。npm のダウンロード数にはリモートコネクターの使用状況は含まれませんが、こちらでは把握できます。

データソースと鮮度

ほとんどのツールはオープンな上流データソース（nflverse、Sleeper、FantasyFootballCalculator、ESPN の公開エンドポイント）からライブデータを取得します。一部のツールは、コミット済みの日次スナップショット（StatHead のブレンド済み dynasty 値、ADP 履歴、自社のシーズン予測）を読み込みます。サーバーはデフォルトで、ホストされている StatHead サイトからこれらを取得します。

このサーバーが返すデータを再配布する前に、DATA_SOURCES.md を確認してください。上流データソースの中には、独自の利用規約が適用されるものや、有料のものがあります。

設定

すべて任意で、環境変数を使って設定します。

変数	デフォルト	用途
STATHEAD_DATA_BASE	GitHub raw（data ブランチ）	コミット済みスナップショットデータ（<base>data/<file>）のベース URL です。デフォルトは GitHub raw です。すべてのファイルを圧縮せず確実に配信します（Cloudflare ホストは 25 MiB の上限を超えるファイルを gzip 圧縮しますが、Node は展開できません）。独自のデプロイ先や、ローカルの http://localhost:5173/ 開発サーバーを指定する場合に上書きしてください。
VITE_KTC_PROXY	プロジェクトの Worker	KeepTradeCut 用の CORS プロキシです。共有のレート制限を避けるには、独自のもの（workers/ktc-proxy）をデプロイしてください。
VITE_FC_PROXY	プロジェクトの Worker	FantasyCalc 用の CORS プロキシです（workers/fc-proxy）。
VITE_ODDS_API_KEY	—	ベッティングオッズのツール（the-odds-api.com）を有効にします。

リポジトリ全体をチェックアウトして実行する場合、サーバーはローカルの public/data/ からスナップショットを直接読み込み、STATHEAD_DATA_BASE を無視します。

ソースからのビルド

バンドルは StatHead モノレポから生成します。

# from the repo root
npm install
npm run build:mcp      # → mcp/dist/server.mjs (esbuild, single file)
node mcp/dist/server.mjs

公開

mcp/package.json の version と mcp/dist/server.mjs の SERVER_VERSION を更新し（両者は一致させる必要があります）、デフォルトブランチにマージしてから、次のいずれかを実行します。

git push -f origin <commit>:publish-mcp-now        # branch-push trigger (works from Claude Code sessions)
git tag mcp-v1.2.3 && git push origin mcp-v1.2.3   # tag trigger
# or Actions → "Publish stathead-mcp to npm" → Run workflow

publish-mcp.yml は、すでに npm に公開されているバージョンや、デフォルトブランチにまだ含まれていないコミットを拒否し、バンドルのスモークテストを行ってから、npm Trusted Publishing 経由で公開し、続けて MCP Registry に公開します。手動で公開する場合は、次の手順を使います。

npm run build:mcp                  # repo root — refresh the bundle
cd mcp && npm publish --access public

公開される tarball に含まれるのは、dist/server.mjs とこの README だけです（約 220 KB）。

MCP レジストリへの登録

server.json は公式の MCP レジストリ （io.github.dachhack/stathead-mcp）向けのマニフェストです。npm への公開後、 MCP レジストリに公開ワークフロー（.github/workflows/publish-mcp-registry.yml） が、io.github.dachhack/* 名前空間用に GitHub OIDC で認証し（シークレット不要）、 これを登録します。npm パッケージには一致する mcpName フィールドが含まれており、 レジストリはこのパッケージがこのエントリーに属することを確認できます。また、 ワークフローは package.json から server.json のバージョンを同期するため、 両者のバージョンがずれることはありません。

コミュニティのディレクトリの多く（Glama、mcp.so、PulseMCP）は公式レジストリを ミラーリングするか、model-context-protocol キーワード（package.json に設定済み） を持つ公開 npm パッケージを自動でインデックス化します。そのため、レジストリへの 公開はこれらのディレクトリにも反映されます。

ライセンス

MIT — ../LICENSE を参照してください。コードは MIT ライセンスですが、 返されるデータは必ずしも再配布できるとは限りません。 DATA_SOURCES.md を参照してください。