stathead-mcp

stathead-mcp

一个 MCP 服务，可将 StatHead 的 NFL Fantasy 数据分析工具集提供给 Claude（Desktop / Code）、Cursor 或任何 MCP 客户端使用 — 你可以用自然语言提问，并获取实时、结构化的 NFL 数据。

它以单个自包含软件包的形式发布，没有运行时依赖项，并按需获取所有数据，因此无需下载或构建 — 运行 npx 即可。

你可以获得什么

涵盖球员和球队数据的 50 个工具，包括：

领域	工具
数据发现	get_metadata — 数据来源、赛季覆盖范围和有效枚举值（先调用此工具，为问题确定范围）
球员	赛季统计、每周／比赛日志、上场次数、伤病、进阶统计、Next Gen Stats、球队名单、合同、get_depth_charts（包含名单状态、StatHead 深度顺序以及用于查看人员变动的 view=changes 的球队位置深度图）
比赛与进攻回合	赛程／结果、逐回合数据、参与情况、FTN 图表数据
Fantasy	StatHead 融合版 dynasty 估值、get_trade_values（根据数百万笔已完成的 Sleeper dynasty 交易拟合的 StatHead 估值：按周提供指定日期的估值及 90% 范围、变动者、流动性、计分规则重新估值、1/3/6/12 个月预测、新秀选秀权类别和历史数据）、get_projections（StatHead 自研赛季场均得分模型）、get_weekly_projections（第 1–18 周经过对阵调整的每周得分）、get_matchups（每周对阵强度：各防守方每场允许 QB/RB/WR/TE 得到的 Fantasy 分数；按你的计分规则以及高于预期的分数从第 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 请求会返回一小段健康状态数据；客户端会向其发送 POST JSON-RPC 请求。）上文的 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——若干上游数据源具有专有性或需要付费，并且各自有适用的条款。

配置

所有配置项均为可选，通过环境变量设置：

Var	默认值	用途
STATHEAD_DATA_BASE	GitHub raw（data 分支）	已提交快照数据的基础 URL（<base>data/<file>）。默认使用 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 monorepo 构建：

# 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） 会将其推送到注册表——通过 GitHub OIDC 对 io.github.dachhack/* 命名空间进行身份验证（无需密钥）。npm 包包含匹配的 mcpName 字段，以便 注册表验证该包属于此条目；工作流还会从 package.json 同步 server.json 的版本，确保二者始终一致。

大多数社区目录（Glama、mcp.so、PulseMCP）会镜像官方注册表，和／或自动索引带有 model-context-protocol 关键词的公开 npm 包（package.json 中已包含该关键词）， 因此发布到注册表后也会同步到这些目录。

许可证

MIT — 请参阅 ../LICENSE。代码采用 MIT 许可证；它返回的数据 不一定可以再分发。请参阅 DATA_SOURCES.md。