Nfl Mcp

NFL MCP Server

A FastMCP 3.0 server that provides health monitoring, web content extraction, NFL news fetching, NFL teams information, and comprehensive fantasy league management through both REST and MCP protocols.

Features

• Health Endpoint: Non-MCP REST endpoint at /health for monitoring server status
• URL Crawling Tool: MCP tool that crawls arbitrary URLs and extracts LLM-friendly text content
• NFL News Tool: MCP tool that fetches the latest NFL news from ESPN API
• NFL Teams Tools: Comprehensive MCP tools for NFL teams including:
• Team data fetching and database caching from ESPN API
• Depth chart retrieval for individual teams
• Fantasy Intelligence APIs: Advanced MCP tools for fantasy football decision making:
• Injury Reports: Real-time injury status for start/sit decisions
• Player Performance Stats: Team player statistics and fantasy relevance indicators
• NFL Standings: League standings with playoff implications and team motivation context
• Team Schedules: Matchup analysis with fantasy implications and strength of schedule
• CBS Fantasy Football Tools: MCP tools for fetching CBS Sports fantasy content:
• Player News: Latest fantasy football player news and updates
• Projections: Weekly player projections by position with customizable scoring formats
• Expert Picks: NFL expert picks against the spread for informed betting and fantasy decisions
• Athlete Tools: MCP tools for fetching, caching, and looking up NFL athletes from Sleeper API with SQLite persistence
• Sleeper API Tools: Comprehensive MCP tools for fantasy league management including:
• League information, rosters, users, matchups, playoff brackets
• Transactions, traded picks, NFL state, trending players
• Flexible Configuration: Environment variables and configuration files (YAML/JSON) with hot-reloading
• HTTP Transport: Runs on HTTP transport protocol (default port 9000)
• Containerized: Docker support for easy deployment
• Well Tested: Comprehensive unit tests for all functionality

Quick Start

Prerequisites

• Python 3.9 or higher
• Docker (optional, for containerized deployment)
• Task (optional, for using Taskfile commands)

Installation

1. Clone the repository:

git clone https://github.com/gtonic/nfl_mcp.git
cd nfl_mcp

1. Install dependencies:

pip install -r requirements.txt
pip install -e ".[dev]"

Running the Server

Local Development

python -m nfl_mcp.server

Using Docker

# Build and run
docker build -t nfl-mcp-server .
docker run --rm -p 9000:9000 nfl-mcp-server

Using Taskfile

# Install task: https://taskfile.dev/installation/
task run          # Run locally
task run-docker   # Run in Docker
task all          # Complete pipeline

Configuration

The NFL MCP Server supports flexible configuration through environment variables and configuration files.

Quick Configuration Examples

Environment Variables

# Set custom timeouts and limits
export NFL_MCP_TIMEOUT_TOTAL=45.0
export NFL_MCP_NFL_NEWS_MAX=75
export NFL_MCP_SERVER_VERSION="1.0.0"

# Advanced enrichment and prefetch (optional)
export NFL_MCP_ADVANCED_ENRICH=1        # Enable snap%, opponent, practice status, usage metrics
export NFL_MCP_PREFETCH=1               # Enable background data prefetch
export NFL_MCP_PREFETCH_INTERVAL=900    # Prefetch interval in seconds (default: 900 = 15 min)
export NFL_MCP_PREFETCH_SNAPS_TTL=1800  # Snap data TTL in seconds (default: 1800 = 30 min)
export NFL_MCP_PREFETCH_SCHEDULE_WEEKS=4 # Number of weeks to prefetch schedules for (default: 4)

# Logging configuration (optional)
export NFL_MCP_LOG_LEVEL=INFO           # Log level: DEBUG, INFO, WARNING, ERROR, CRITICAL (default: INFO)

# Run the server
python -m nfl_mcp.server

Note: Logging is enabled at INFO level by default, providing comprehensive tracking of prefetch operations, enrichment activity, and API calls.

Configuration File (config.yml)

timeout:
  total: 45.0
  connect: 15.0

limits:
  nfl_news_max: 75
  athletes_search_max: 150

rate_limits:
  default_requests_per_minute: 120

security:
  max_string_length: 2000

Docker with Environment Variables

docker run --rm -p 9000:9000 \
  -e NFL_MCP_TIMEOUT_TOTAL=45.0 \
  -e NFL_MCP_RATE_LIMIT_DEFAULT=120 \
  -e NFL_MCP_ADVANCED_ENRICH=1 \
  -e NFL_MCP_PREFETCH=1 \
  -e NFL_MCP_LOG_LEVEL=INFO \
  nfl-mcp-server

API Documentation

📋 [AI/LLM Integration Guide](./AGENT.md) - Comprehensive MCP tool reference and integration guide optimized for LLM understanding

📊 [Coaching Data Research](./docs/COACHINGDATARESEARCH.md) - Research on coaching data sources for performance forecasts and 2026 draft analysis

Quick Overview

The NFL MCP Server provides 30+ MCP tools organized into these categories:

🏈 NFL Information (9 tools)

• get_nfl_news - Latest NFL news from ESPN
• get_teams - All NFL team information
• fetch_teams - Cache teams in database
• get_depth_chart - Team roster/depth chart
• get_team_injuries - Injury reports by team
• get_team_player_stats - Team player statistics
• get_nfl_standings - Current NFL standings
• get_team_schedule - Team schedules with fantasy context
• get_league_leaders - NFL statistical leaders by category

🧠 Coaching Intelligence (4 tools)

• get_coaching_staff - Team coaching staff (head coach, coordinators, position coaches)
• get_all_coaching_staffs - Coaching staff summary for all 32 NFL teams
• get_coaching_tree - Coach mentors, proteges, and scheme family
• get_scheme_classification - Team offensive/defensive scheme classification

📰 CBS Fantasy Football (3 tools)

• get_cbs_player_news - Latest fantasy football player news from CBS Sports
• get_cbs_projections - Fantasy projections by position and week from CBS Sports
• get_cbs_expert_picks - NFL expert picks against the spread from CBS Sports

👥 Player/Athlete (4 tools)

• fetch_athletes - Import all NFL players (expensive, use sparingly)
• lookup_athlete - Find player by ID
• search_athletes - Search players by name
• get_athletes_by_team - Get team roster

🌐 Web Scraping (1 tool)

• crawl_url - Extract text from any webpage

🏆 Fantasy League - Sleeper API (Expanded)

• Core League: get_league, get_rosters, get_league_users
• Match / Brackets: get_matchups, get_playoff_bracket (now supports winners|losers via bracket_type)
• Activity & Assets: get_transactions (week required), get_traded_picks
• Draft Data: get_league_drafts, get_draft, get_draft_picks, get_draft_traded_picks
• Global / Meta: get_nfl_state, get_trending_players, fetch_all_players (large players map w/ caching)

🎯 Lineup Optimization (11 tools)

• Matchup Analysis: get_defense_rankings, get_matchup_difficulty, analyze_roster_matchups
• Start/Sit Recommendations: get_start_sit_recommendation, get_roster_recommendations, compare_players_for_slot, analyze_full_lineup
• Vegas Lines: get_vegas_lines, get_game_environment, analyze_roster_vegas, get_stack_opportunities

❤️ Health Endpoint (REST)

• GET /health - Server status monitoring

Tool Selection Guide

For LLMs: The [AI/LLM Integration Guide](./AILLMGUIDE.md) includes:

• 🎯 When to use each tool - Decision matrix for tool selection
• 📊 Parameter validation - Input constraints and validation rules
• 💡 Usage patterns - Common workflows and examples
• ⚡ Performance notes - Which tools are expensive vs. fast
• 🛡️ Error handling - Consistent error response patterns

Basic Usage Example

from fastmcp import Client

async with Client("http://localhost:9000/mcp/") as client:
    # Get latest NFL news
    news = await client.call_tool("get_nfl_news", {"limit": 5})
    
    # Search for a player
    player = await client.call_tool("search_athletes", {"name": "Mahomes"})
    
    # Get team depth chart
    depth = await client.call_tool("get_depth_chart", {"team_id": "KC"})

Sleeper Enhancements (Recent)

Recent upgrades to Sleeper tooling:

• Added losers bracket support: get_playoff_bracket(league_id, bracket_type="losers")
• Enforced explicit week for get_transactions (or alias round) to match official API
• Trending players now preserves Sleeper-provided count and enriches with local athlete data under enriched
• Added draft suite (get_league_drafts, get_draft, get_draft_picks, get_draft_traded_picks)
• Added full players dataset endpoint fetch_all_players with 12h in-memory TTL (returns metadata, not massive map)
• Added enrichment across core endpoints (rosters, matchups, transactions, traded picks, draft picks, trending)
• Automatic week inference for get_transactions (adds auto_week_inferred)
• Aggregator endpoint get_fantasy_context to batch league core data (optional include)
• Introduced central param validator utility (param_validator.py) for future consolidation
• Robustness layer (retry + snapshot fallback) for: get_rosters, get_transactions, get_matchups
• Snapshot metadata fields now returned:
• retries_used: number of retry attempts consumed
• stale: indicates if served data came from a snapshot beyond freshness TTL
• failure_reason: last encountered failure code/category
• snapshot_fetched_at, snapshot_age_seconds: present when snapshot used (or null on fresh)

Additional Enrichment (Schema v7)

New optional fields may appear within players_enriched, starters_enriched, and transaction add/drop enrichment objects:

| Field | Description | Source Values | |-------|-------------|---------------| | snap_pct | Offensive snap percentage for the current week (float, one decimal) | Derived or cached | | snap_pct_source | Provenance for snap_pct | cached, estimated | | opponent | Opponent team abbreviation (for DEF entries) | Schedule cache | | opponent_source | Provenance for opponent | cached, fetched |

Notes:

• Estimated snap% uses depth-chart heuristics (starter≈70, #2≈45, others≈15) when real stats absent.
• All fields are additive and may be absent without breaking existing consumers.

Enhanced Enrichment (Schema v8)

Additional practice status & usage metrics (requires NFL_MCP_ADVANCED_ENRICH=1):

| Field | Description | Values/Format | |-------|-------------|---------------| | practice_status | Latest injury practice designation | DNP, LP, FP, Full | | practice_status_date | Date of practice report | ISO date (YYYY-MM-DD) | | practice_status_age_hours | Age of practice report in hours | Float (1 decimal) | | practice_status_stale | Report older than 72h | Boolean | | usage_last_3_weeks | Avg usage metrics (WR/RB/TE only) | Object (see below) | | usage_source | Provenance for usage data | sleeper, estimated | | usage_trend | Trend analysis per metric (WR/RB/TE) | Object (see below) | | usage_trend_overall | Overall usage trend direction | up, down, flat |

Usage Object Fields:

• targets_avg: Average targets per game (1 decimal)
• routes_avg: Average routes run per game (1 decimal)
• rz_touches_avg: Average red zone touches per game (1 decimal)
• snap_share_avg: Average snap share percentage (1 decimal)
• weeks_sample: Number of weeks in sample (1-3)

Usage Trend Object Fields:

• targets: Trend for targets (up/down/flat)
• routes: Trend for routes run (up/down/flat)
• snap_share: Trend for snap percentage (up/down/flat)

Notes:

• Practice status helps identify injury risk (DNP = high risk, LP = moderate, FP/Full = low)
• Usage metrics provide true volume indicators beyond depth chart position
• Trend calculation compares most recent week vs prior weeks (15% threshold)
• Trend "up" (↑) = rising usage, "down" (↓) = declining usage, "flat" (→) = stable usage
• All fields are additive; absent fields mean data unavailable

Robustness & Snapshot Behavior

Each robust endpoint attempts multiple fetches with backoff. If all fail, the server returns the most recent cached snapshot with success=false but still provides usable data so LLM workflows can continue gracefully. Always check:

{
  "success": false,
  "stale": true,
  "retries_used": 3,
  "failure_reason": "timeout",
  "snapshot_fetched_at": "2025-09-13T11:22:33Z",
  "snapshot_age_seconds": 642
}

For fresh successful responses the snapshot fields are present with null values (allowing uniform downstream parsing).

Aggregator Quick Use

get_fantasy_context(league_id="12345", include="league,rosters,matchups")

If week omitted it will be inferred from NFL state. Response includes week and auto_week_inferred.

Updated Transactions Behavior

Calling get_transactions(league_id) without week now attempts inference; falls back to validation error only if NFL state unavailable.

Architecture Improvements

Simplified Design (v2.0):

• ✅ Single Tool Registry - All tools defined in one place
• ✅ 92% Code Reduction - Server simplified from 766 to 59 lines
• ✅ Zero Duplication - Eliminated redundant tool definitions
• ✅ Clean Dependencies - Straightforward import structure

Health Endpoint (REST)

GET /health

Returns server health status.

Response:

{
  "status": "healthy",
  "service": "NFL MCP Server", 
  "version": "0.1.0"
}

NFL News Tool (MCP)

Tool Name: get_nfl_news

Fetches the latest NFL news from ESPN API and returns structured news data.

Parameters:

• limit (integer, optional): Maximum number of news articles to retrieve (default: 50, max: 50)

Returns: Dictionary with the following fields:

• articles: List of news articles with headlines, descriptions, published dates, etc.
• total_articles: Number of articles returned
• success: Whether the request was successful
• error: Error message (if any)

Example Usage with MCP Client:

from fastmcp import Client

async with Client("http://localhost:9000/mcp/") as client:
    result = await client.call_tool("get_nfl_news", {"limit": 10})
    
    if result.data["success"]:
        print(f"Found {result.data['total_articles']} articles")
        for article in result.data["articles"]:
            print(f"- {article['headline']}")
            print(f"  Published: {article['published']}")
    else:
        print(f"Error: {result.data['error']}")

Article Structure: Each article in the articles list contains:

• headline: Article headline
• description: Brief description/summary
• published: Publication date/time
• type: Article type (Story, News, etc.)
• story: Full story content
• categories: List of category descriptions
• links: Associated links (web, mobile, etc.)

NFL Teams Tools (MCP)

Tools: get_teams, fetch_teams, get_depth_chart

These tools provide comprehensive NFL teams data management with database caching and depth chart access.

get_teams

Fetches all NFL teams from ESPN API and returns structured team data.

Parameters: None

Returns: Dictionary with the following fields:

• teams: List of teams with comprehensive team information
• total_teams: Number of teams returned
• success: Whether the request was successful
• error: Error message (if any)

fetch_teams

Fetches all NFL teams from ESPN API and stores them in the local database for caching.

Parameters: None

Returns: Dictionary with the following fields:

• teams_count: Number of teams processed and stored
• last_updated: Timestamp of the update
• success: Whether the fetch was successful
• error: Error message (if any)

getdepthchart

Fetches the depth chart for a specific NFL team from ESPN.

Parameters:

• team_id: Team abbreviation (e.g., 'KC', 'TB', 'NE')

Returns: Di

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: gtonic
• Source: gtonic/nfl_mcp
• License: MIT

Install and usage instructions live in the source repository linked above.