Stathead MCP Server

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.md before 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.