Stathead MCP

stathead-mcp

An MCP server that exposes StatHead's NFL fantasy-analytics toolset to Claude (Desktop / Code), Cursor, or any MCP client — so you can ask natural-language questions and get live, structured NFL data back.

It ships as a single self-contained bundle with no runtime dependencies and fetches all data on demand, so there's nothing to download or build — npx and go.

What you get

50 tools spanning player and team data, including:

Bring your own projections & rankings

The same boards the website lets you download are available over MCP as real .xlsx files (built with zero extra dependencies — Node's own zlib):

1. export_excel kind="projections" (or rankings, rookie_rankings) writes a styled workbook to disk and returns its path. Edit the highlighted column — Proj PPG for projections, My Rank for rankings/rookies — in Excel or Google Sheets.
2. import_excel path="…" reads it back and saves your values as overrides.
3. get_projections, get_fantasy_rankings, and get_prospect_outcomes then automatically use your numbers (flagged in the output) until you run clear_overrides.

Workbooks default to $STATHEAD_DIR (or the current working directory); pass path to choose where they land. Overrides persist in $STATHEAD_DIR/~/.stathead/overrides.json.

Quick start

Run it directly — no install, no clone:

npx -y stathead-mcp

It speaks MCP over stdio, so you normally wire it into a client rather than run it by hand.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %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 / other MCP clients

Use the same command/args (npx -y stathead-mcp) in the client's MCP config.

Claude mobile apps / claude.ai web / Claude Desktop (remote connector)

Prefer a URL over a local command? The same tools are hosted over MCP's Streamable HTTP transport by a Cloudflare Worker (workers/stathead-mcp/, deployed via deploy-workers.yml):

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

Add it under Settings → Connectors → Add custom connector, paste the URL, and save — no command, no API key. (A GET to that URL returns a small health payload; clients POST JSON-RPC to it.) The npm/stdio package above stays the path for Claude Code and Cursor.

The Worker records a privacy-respecting usage counter (MCP method + tool name only — no IPs or request bodies) to a Cloudflare Analytics Engine dataset (stathead_mcp_usage). View aggregates at GET /stats once you set the CF_ACCOUNT_ID + CF_ANALYTICS_TOKEN worker secrets (wrangler secret put …), or query the dataset in the Cloudflare dashboard. npm download counts don't see remote-connector usage — this does.

Data sources & freshness

Most tools fetch live from open upstreams (nflverse, Sleeper, FantasyFootballCalculator, ESPN's public endpoints). A handful read committed daily snapshots (StatHead's blended dynasty values, ADP history, in-house season projections), which the server fetches from the hosted StatHead site by default.

Please review [`DATA_SOURCES.md`](../DATA_SOURCES.md) before redistributing any data this server returns — several upstreams are proprietary or paid and carry their own terms.

Configuration

All optional, via environment variables:

Running from a full repo checkout instead? The server reads snapshots straight from local public/data/ and ignores STATHEAD_DATA_BASE.

Building from source

The bundle is produced from the StatHead monorepo:

# from the repo root

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

Publishing

Bump version in mcp/package.json and SERVER_VERSION in mcp/dist/server.mjs (they must match), merge to the default branch, then any one of:

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 refuses a version already on npm and a commit not yet on the default branch, smoke-tests the bundle, publishes via npm Trusted Publishing, then chains the MCP Registry publish. Manual fallback:

npm run build:mcp                  # repo root — refresh the bundle

cd mcp && npm publish --access public

The published tarball is just dist/server.mjs + this README (~220 KB).

Listing in the MCP Registry

server.json is the manifest for the official MCP Registry (io.github.dachhack/stathead-mcp). After an npm publish, the Publish to MCP Registry workflow (.github/workflows/publish-mcp-registry.yml) pushes it — authenticating via GitHub OIDC for the io.github.dachhack/* namespace (no secret). The npm package carries a matching mcpName field so the registry can verify the package belongs to this entry, and the workflow syncs server.json's version from package.json so they never drift.

Most community directories (Glama, mcp.so, PulseMCP) mirror the official registry and/or auto-index public npm packages with the model-context-protocol keyword (which package.json has), so a registry publish propagates to them.

License

MIT — see ../LICENSE. The code is MIT; the data it returns is not necessarily redistributable. See DATA_SOURCES.md.