NFL Data MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@NFL Data MCP search for Patrick Mahomes"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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/previousseason referencesMulti-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-mcpThis installs three commands:
nfl-data-mcp— start the MCP server over stdionfl-data-sync— optionally prefetch datasetsnfl-data-doctor— inspect the local cache
Upgrade or remove it with:
uv tool upgrade nfl-data-mcp
uv tool uninstall nfl-data-mcpThe 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-mcpExample 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
pytestThe 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=autoThe 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-mcpFor 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-doctorThe 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_playersget_playerget_player_statsget_team_statsfind_stat_gamesfind_stat_seasonsget_scheduleget_gameget_scoring_eventsget_game_statslist_teamsget_team_rosterget_injuriesget_depth_chartget_snap_countsget_stat_leaderslist_stat_fieldsget_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 buildData 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 toolsfind_stat_seasonsCRead-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_statusBRead-onlyIdempotent
Report local dataset coverage, snapshot versions, and as-of classifications.
Inputs: dataset. Returns: object
get_depth_chartCRead-onlyIdempotent
Get a factual team depth chart for a season and week.
Inputs: team (required), week (required), season (required), position. Returns: object
get_gameARead-onlyIdempotent
Get one scheduled or completed NFL game by canonical game ID.
Inputs: game_id (required), season. Returns: object
get_game_statsBRead-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_injuriesCRead-onlyIdempotent
Get official injury and practice-report records.
Inputs: week (required), season (required), team, limit, +1 more. Returns: object
get_scheduleCRead-onlyIdempotent
Get bounded NFL games for a season, week, or team.
Inputs: season (required), team, week, limit, +1 more. Returns: object
get_stat_leadersCRead-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_rosterCRead-onlyIdempotent
Get a team's factual weekly NFL roster.
Inputs: team (required), week (required), season (required), positions. Returns: object
list_stat_fieldsBRead-onlyIdempotent
List valid factual statistic names for player/team leader and stat queries.
Inputs: unit (required), season (required), entity_type (required). Returns: object
list_teamsARead-onlyIdempotent
List canonical NFL team abbreviations and metadata.
Inputs: no named parameters. Returns: object
search_playersARead-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
Scored across 12 tools
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.
All tool names follow a verb_noun pattern using snake_case: get_, list_, find_, search_. No mixed conventions or inconsistent styles.
12 tools cover the essential NFL data endpoints well without being excessive. The count is appropriate for a focused sports data server.
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
Related MCP Connectors
NFL player props by sportsbook since 2023, plus play-by-play with EPA, stats and odds. REST and MCP.
Unofficial SportsDataIO MCP — wraps SportsDataIO's Big-Six sports data API (sportsdata.io)
Token-free MCP server for structured RevoGrid Core, Pro, and Enterprise knowledge retrieval.
NFL analytics tools for AI agents: stats, fantasy, injuries, schedules, and advanced analysis.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceAn 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 PyPI9MIT
- AlicenseNot gradedqualityBmaintenanceAn 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.3MIT
- AlicenseNot gradedqualityDmaintenanceMCP 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
- AlicenseNot gradedqualityCmaintenanceProvides 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