Skip to main content
Glama
NFL Data MCP

NFL Data MCP

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.

Related MCP server: StatHead

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.

Available Tools

12 tools
find_stat_seasonsC
Read-onlyIdempotent

Find career-high, career-low, first, or last season totals for a statistic.

Inputs: stat (required), unit (required), entity_id (required), entity_type (required), +7 more. Returns: object

get_data_statusB
Read-onlyIdempotent

Report local dataset coverage, snapshot versions, and as-of classifications.

Inputs: dataset. Returns: object

get_depth_chartC
Read-onlyIdempotent

Get a factual team depth chart for a season and week.

Inputs: team (required), week (required), season (required), position. Returns: object

get_gameA
Read-onlyIdempotent

Get one scheduled or completed NFL game by canonical game ID.

Inputs: game_id (required), season. Returns: object

get_game_statsB
Read-onlyIdempotent

Get a factual player or team box score for one canonical game ID.

Inputs: game_id (required), unit, limit, season, +1 more. Returns: object

get_injuriesC
Read-onlyIdempotent

Get official injury and practice-report records.

Inputs: week (required), season (required), team, limit, +1 more. Returns: object

get_scheduleC
Read-onlyIdempotent

Get bounded NFL games for a season, week, or team.

Inputs: season (required), team, week, limit, +1 more. Returns: object

get_stat_leadersC
Read-onlyIdempotent

Rank players or teams by one factual statistic.

Inputs: stat (required), unit (required), season (required), entity_type (required), +3 more. Returns: object

get_team_rosterC
Read-onlyIdempotent

Get a team's factual weekly NFL roster.

Inputs: team (required), week (required), season (required), positions. Returns: object

list_stat_fieldsB
Read-onlyIdempotent

List valid factual statistic names for player/team leader and stat queries.

Inputs: unit (required), season (required), entity_type (required). Returns: object

list_teamsA
Read-onlyIdempotent

List canonical NFL team abbreviations and metadata.

Inputs: no named parameters. Returns: object

search_playersA
Read-onlyIdempotent

Resolve active or retired player names; set active_only=true to exclude retirees.

Inputs: query (required), team, limit, position, +1 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 12 tools

    Disambiguation5/5

    Each tool targets a distinct data aspect: schedule, game, stats, roster, depth chart, injuries, players, teams, status, and stat fields. There is no overlap in purpose.

    Naming Consistency5/5

    All tool names follow a verb_noun pattern using snake_case: get_, list_, find_, search_. No mixed conventions or inconsistent styles.

    Tool Count5/5

    12 tools cover the essential NFL data endpoints well without being excessive. The count is appropriate for a focused sports data server.

    Completeness5/5

    The tool surface covers core NFL data needs: schedule, games, stats, rosters, depth charts, injuries, player search, team listing, and metadata. No significant gaps for a read-only data server.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      An MCP server that provides access to over 12 years of NFL play-by-play data through a local DuckDB database. It enables users to query player performance, team statistics, and situational efficiency metrics like EPA and WPA using natural language.
      28 PyPI
      9
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      An open NFL fantasy-football analytics platform that provides live data, machine-learned projections, dynasty values, and prospect grades via an MCP server for AI clients.
      3
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that turns real NFL & fantasy data into a decisive edge, offering 70+ tools for draft assistance, start/sit recommendations, trade analysis, playoff odds, and more, with live league integration.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides verified NFL stats (2016–2025) and Sleeper league context through an MCP server, with tools for querying metrics, comparing entities, verifying claims, and accessing league data.
      MIT