Documentation menu

nfl_matchup_analysis

Pro tier

Matchup analysis

Use nfl_schedule first to discover the exact game_id, then use this Pro tool for deterministic game previews, team-position matchup grades, or strength-of-schedule rankings. It returns source games/weeks, sample sizes, confidence, coverage, and freshness, with prior-season fallback when current-season history is insufficient and no data after the selected cutoff. Do not use this tool for raw schedules/results, individual player box scores, standalone injury reports, arbitrary SQL, win probabilities, model prose, betting recommendations, or picks.

Minimum tier: Pro
Data coverage: Varies by query

Parameters

Name	Type	Required	Description
`analysis_type`	string	Required	Discriminator selecting exactly one compact analysis mode.Options: game_preview, position_matchup, strength_of_schedule
`game_id`	string	Optional	Exact game ID from nfl_schedule; required for game_preview and position_matchup.
`team`	string	Optional	For position_matchup, one of the game's teams. For SOS, optional team abbreviation; omit to rank the league.
`position`	string	Optional	Required for position_matchup and strength_of_schedule.Options: QB, RB, WR, TE
`season`	integer	Optional	Required only for strength_of_schedule.
`start_week`	integer	Optional	Required only for strength_of_schedule.
`end_week`	integer	Optional	Required only for strength_of_schedule; must be >= start_week.
`lookback_games`	integer	Optional	Completed games used for recent form. Defaults to 5 for game_preview and 6 otherwise; game_preview maximum is 10.
`limit`	integer	Optional	SOS league-ranking result limit (default 32); not accepted by game modes.

Example request

A Model Context Protocol tools/call over Streamable HTTP. Replace YOUR_API_KEY with a key from your dashboard.

curl -X POST https://mcp.nflmcp.com/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "nfl_matchup_analysis",
    "arguments": {
      "analysis_type": "position_matchup",
      "game_id": "2024_01_BAL_KC",
      "team": "KC",
      "position": "WR"
    }
  }
}'

Example response

Excerpt · lists trimmed

{
  "analysis_type": "position_matchup",
  "game_id": "2024_01_BAL_KC",
  "team": "KC",
  "opponent": "BAL",
  "position": "WR",
  "season_grade": null,
  "recent_grade": {
    "percentile": 16.129,
    "rank": 27,
    "league_size": 32
  },
  "combined_grade": {
    "percentile": 16.129,
    "label": "very_difficult",
    "scoring_version": "matchup_v1",
    "rank": 27,
    "league_size": 32
  },
  "production_allowed": {
    "fantasy_points_per_game": 27.633,
    "opportunities_per_game": 18,
    "yards_per_game": 121.667,
    "touchdowns_per_game": 0.667
  },
  "sample_size": {
    "season_games": 0,
    "recent_games": 6,
    "requested_lookback_games": 6
  },
  "source": {
    "seasons": [
      2023,
      2023,
      2023
    ],
    "weeks": [
      15,
      16,
      17
    ],
    "games": [
      "2023_15_BAL_JAX",
      "2023_16_BAL_SF",
      "2023_17_MIA_BAL"
    ],
    "available_seasons": [
      2013,
      2014,
      2015
    ],
    "fallback_season": 2023,
    "prior_season_fallback": true
  },
  "confidence": "low",
  "drivers": [
    {
      "metric": "fantasy_points_per_game",
      "value": 27.6333
    },
    {
      "metric": "opportunities_per_game",
      "value": 18
    },
    {
      "metric": "yards_per_game",
      "value": 121.6667
    }
  ],
  "coverage": {
    "available": true,
    "source": "player_stats_snapshot",
    "as_of": "2026-03-07 00:45:54.663760",
    "cutoff": "2024-09-05 20:20"
  }
}

All tools