StatHead
An open NFL fantasy-football analytics platform — live data, machine-learned projections, dynasty values, and prospect grades, served as a web app and as an MCP server you can plug straight into Claude or any AI client.
- 🌐 Web app — stathead.app (QA mirror)
- 🤖 MCP server — 30 NFL tools for AI projects →
mcp/ - 🧠 ML pipeline — projection / dynasty-value / prospect models trained from 10+ seasons of data
- 📦 MIT-licensed code. ⚠️ The data has its own terms —
see
DATA_SOURCES.mdbefore redistributing anything.
Use it in your own AI project (MCP)
The fastest way to build on StatHead. No clone, no build:
npx -y stathead-mcp
Claude Code:
claude mcp add stathead -- npx -y stathead-mcp
Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"stathead": { "command": "npx", "args": ["-y", "stathead-mcp"] }
}
}
Then ask things like "Compare Bijan Robinson's and Jahmyr Gibbs' weekly
consistency in 2024" or "Top 10 dynasty WRs by StatHead value, with their
ages." Full tool list and configuration: mcp/README.md.
Run the web app locally
npm install
npm run dev # Vite dev server
Other useful scripts:
The repo is a TypeScript/React (Vite) front end plus a TypeScript + Python data
& ML pipeline under scripts/ and python/. The same
tool layer (src/tools.ts → src/data.ts) backs both the app and the MCP
server.
Data
StatHead pulls from many upstreams — open data (nflverse, DynastyProcess, CFBD), public APIs (Sleeper, ESPN, FantasyFootballCalculator), proprietary community values (KeepTradeCut, FantasyCalc), and derived features from paid scouting products. Licensing varies a lot by source.
👉 Read DATA_SOURCES.md before redistributing data,
publishing a dataset, or shipping a commercial product. The short version:
share the open sources and StatHead's own model outputs freely; fetch the rest
from the original source under your own access rather than rebundling it.
Data proxies (self-hosting)
Live KeepTradeCut, FantasyCalc, and ESPN data is fetched through small
Cloudflare Worker CORS proxies, because those upstream APIs block direct
browser requests. The worker source lives under workers/ and a
deploy workflow is in
.github/workflows/deploy-workers.yml.
By default the app points at the upstream project's workers, so it works as
soon as you clone it. If you deploy your own copy, stand up your own workers
(so you don't depend on — or get rate-limited by — someone else's) and override
the URLs via env vars. Copy .env.example to .env.local and set:
Each falls back to the project's worker when unset. Deploy a worker with
cd workers/<name> && npx wrangler deploy (or use the deploy workflow).
Visitor analytics
The app sends a first-party, cookie-less pageview beacon per tab view to
workers/visit-tracker, which writes to Cloudflare
Workers Analytics Engine. No third parties, no identifiers stored in the
browser, no raw IPs kept — visitors are counted with a daily-rotating
anonymous hash, and Do Not Track / Global Privacy Control are honored.
Aggregates (daily views/visitors, top pages, referrers, countries) are served
by the worker's /stats endpoint and a small dashboard at its root URL. See
the worker's header comment for the data layout and the one-time
CLOUDFLARE_ANALYTICS_API_TOKEN setup.
Environments
Two deploy targets, fed by the same codebase:
The base path is set by the BASE_PATH env var in
vite.config.ts (default /stathead/); the prod
workflow builds with BASE_PATH=/. Everything in the app reads
import.meta.env.BASE_URL, so that one switch repoints every asset and
data URL.
Promote QA → prod by merging the dev branch into production. That
push builds for the root domain and uploads to Cloudflare Pages. See the
header of deploy-prod.yml for the
one-time Cloudflare Pages + DNS setup.
License
Code is MIT. Data is not covered by that license — see
DATA_SOURCES.md. The name "Stathead" may conflict with
Sports Reference's Stathead trademark; see the note in
that file.
