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
• 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

Until the first PyPI upload, install a local wheel with uv tool install dist/nfl_data_mcp-0.1.1-py3-none-any.whl.

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_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.

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.