nfl-mcp

MCP server for NFL data (2013 through the current season), powered by nflreadpy and DuckDB. Query play-by-play, rosters, injuries, stats, and more using natural language in Claude Code, VS Code, or Claude Desktop.

Ask Claude questions like:

• “Who had the best EPA per play in 2024?”
• “Show me Patrick Mahomes’ completion % over expected by season”
• “Compare 4th quarter red zone efficiency for KC vs PHI in 2023”
• “Which defenses had the highest sack rate in 3rd & long situations?”
• “Who was on IR for the Eagles in Week 10, 2023?”
• “Show me snap count trends for the Chiefs receiving corps in 2024”

Quickstart

pip install nfl-mcp        # or: uvx nfl-mcp
nfl-mcp init               # configure, load data, and start the server

init walks you through setup and offers to start the server immediately when done. No database server to install. No credentials to manage. Data is stored locally in DuckDB and can be refreshed through today with nfl-mcp update.

Deploy to Azure

Run the server in the cloud as an Azure Container App with one click:

The button opens the Azure portal’s Custom deployment blade prefilled from infra/azuredeploy.json. Pick a resource group, then Create. It provisions a Container Apps Environment, a Log Analytics workspace, and the Container App (public HTTPS ingress on port 8000). When the deployment finishes, the mcpUrl output is your endpoint — point any MCP client at https://..azurecontainerapps.io/mcp.

The data is baked into the image. The full DuckDB database is built into the container image at build time, so the app serves read-only with no runtime ingest — it starts instantly, never re-downloads data, needs no external storage, and runs comfortably on 0.5 vCPU / 1Gi. To refresh the data, rebuild the image (re-run the publish workflow); the Publish container image workflow also rebuilds weekly. The replica is pinned to a single instance (minReplicas = maxReplicas = 1).

One-time setup before the button works:

1. The Publish container image workflow must have pushed an image to ghcr.io/ebhattad/nfl-mcp (it runs weekly, on each GitHub release, or manually via Actions → Run workflow). The build ingests all default datasets, so it takes longer than a normal image build.
2. Make that GHCR package public: repo → Packages → nfl-mcp → Package settings → Change visibility → Public. The ARM template pulls the image without credentials, so it must be public.

Prerequisites

• Python 3.10+