NFL Data MCP

A standalone, provenance-aware factual NFL data server for MCP clients and downstream analytics. In the default auto mode, the server retrieves missing or stale data from nflverse through nflreadpy and keeps a transparent local DuckDB cache.

Public alpha: tool contracts are usable, tested, and versioned, but may change before 1.0. This project is independent and is not affiliated with the NFL.

The factual v0.1 surface provides:

• Canonical player search
• Player profiles
• Complete weekly player and team statistics across offense, defense, special teams, and miscellaneous categories
• NFL schedules
• Factual scoring events classified by offense, defense, or special teams
• Teams, individual games, weekly rosters, injuries, depth charts, and snap counts
• Player and team statistical leaderboards
• Automatic on-demand retrieval with last-known-good fallback
• Friendly team names and current/upcoming/previous season references
• Multi-season cache retention
• Cache, source, freshness, and as-of provenance
• stdio transport

Fantasy scoring, projections, rankings, ADP, recommendations, and league state are intentionally outside this package.

Install

The server requires Python 3.12. The simplest isolated installation uses uv:

uv tool install nfl-data-mcp

This installs three commands:

• nfl-data-mcp — start the MCP server over stdio
• nfl-data-sync — optionally prefetch datasets
• nfl-data-doctor — inspect the local cache

Upgrade or remove it with:

uv tool upgrade nfl-data-mcp
uv tool uninstall nfl-data-mcp

The package is also available from PyPI.

Connect an MCP client

Configure an MCP client to launch the installed nfl-data-mcp executable. GUI applications often have a smaller PATH than your terminal, so use the absolute path printed by:

command -v nfl-data-mcp

Example Claude Desktop entry:

{
  "mcpServers": {
    "nfl-data": {
      "command": "/absolute/path/to/nfl-data-mcp",
      "args": [],
      "env": {
        "NFL_MCP_MODE": "auto"
      }
    }
  }
}

Fully restart the client after changing its configuration or upgrading the package. See docs/client-setup.md for cache paths, offline mode, and troubleshooting.

Development setup

uv sync --extra dev
source .venv/bin/activate
pytest

The workspace uses Python 3.12. uv will honor .python-version.

Runtime configuration

Configuration uses NFL_MCP_ environment variables:

export NFL_MCP_DATA_DIR="$PWD/data"
export NFL_MCP_MODE=auto

The default data directory is the operating system's user-data location. For local development, setting NFL_MCP_DATA_DIR to a repository-local ignored directory is recommended.

Modes:

• auto (default): use fresh cache data, retrieve missing/stale data, and fall back to stale data with a warning if the source is temporarily unavailable.
• offline: only use cached data and never access the network.
• snapshot: read only the prepared catalog, with no automatic updates. Use a dedicated immutable data directory for reproducible simulations.

Run from source

No manual synchronization is required in normal use:

cp .env.example .env
nfl-data-mcp

For example, an MCP client can ask for the Jets schedule using:

{"season": "upcoming", "team": "Jets"}

The first call retrieves that season's schedule. Later calls use the cache until its dataset-specific freshness window expires.

Administrative prefetching is still available:

nfl-data-sync --season 2026 --datasets schedules --allow-network
nfl-data-doctor

The public v0.1 server runs over local stdio only. Remote HTTP transport is deferred until authentication, tenant isolation, and production request limits are implemented.

Available MCP tools

• search_players
• get_player
• get_player_stats
• get_team_stats
• find_stat_games
• find_stat_seasons
• get_schedule
• get_game
• get_scoring_events
• get_game_stats
• list_teams
• get_team_roster
• get_injuries
• get_depth_chart
• get_snap_counts
• get_stat_leaders
• list_stat_fields
• get_data_status

All tools are read-only and bounded. Use search_players first, then pass the returned canonical player_id to player-specific tools. Retired players are included by default; pass active_only=true when only active players should match. Both statistics tools use the same unit values: offense, defense, special_teams, miscellaneous, or all.

Statistics can cover one season, an explicit season list, or an entire career:

{
  "player_ids": ["00-0034857"],
  "seasons": [2022, 2023, 2024],
  "unit": "offense",
  "aggregation": "season"
}

Use seasons="career" with aggregation="career" for a career summary. Use find_stat_games for questions such as “In what game did this player record his first interception?” Use find_stat_seasons for questions such as “What was this player's career-high passing-yard season?” The per-stat rules are documented in docs/stat-aggregation.md.

get_scoring_events returns factual scoring plays rather than fantasy points. It identifies the scoring and conceding teams, possession team, event type, scoring unit, and point value so downstream systems can apply their own D/ST points-allowed policy. See docs/scoring-events.md.

Verify the project

uv run ruff format --check src tests
uv run ruff check src tests
uv run mypy src
uv run pytest
uv build

Data guarantees

Every response identifies its source snapshot and point-in-time classification. Metadata also includes mode, cache_status, freshness, and warnings. The cache is not the server's data boundary: in auto mode it fills itself from the documented upstream source. Week-keyed historical records are not automatically claimed to represent everything known at that historical moment. Unsupported knowledge-time queries fail explicitly instead of silently returning later-corrected data.

Downloaded NFL data is not included in this repository. Source attribution and licensing requirements still apply to cached data and downstream redistribution. See THIRD_PARTY_NOTICES.md.

License and support

The software is licensed under the Apache License 2.0. Runtime data has separate upstream terms documented in THIRD_PARTY_NOTICES.md. See SECURITY.md for vulnerability reporting and CONTRIBUTING.md for development guidelines.