Documentation menu

nfl_compare

Free tier

Compare

PREFERRED for any comparison question. Side-by-side stats for two teams or two players in a single call. Always use this instead of calling nfl_team_stats or nfl_player_stats twice when the user asks to compare, rank, or contrast two teams or two players against each other. For ambiguous player names, pass the matching entityN_team or entityN_gsis_id in this same call.

Minimum tier: Free
Data coverage: Varies by query

Parameters

Name	Type	Required	Description
`entity1`	string	Required	First team abbreviation or player name
`entity2`	string	Required	Second team abbreviation or player name
`compare_type`	string	Optional	Whether comparing teams or players. Omit to infer when both inputs have the same type.Options: team, player
`entity1_team`	string	Optional	Optional team abbreviation that disambiguates entity1 when comparing players.
`entity2_team`	string	Optional	Optional team abbreviation that disambiguates entity2 when comparing players.
`entity1_gsis_id`	string	Optional	Optional exact GSIS player id that disambiguates entity1.
`entity2_gsis_id`	string	Optional	Optional exact GSIS player id that disambiguates entity2.
`season`	integer	Optional	Exact season year. Omit for all seasons.
`season_from`	integer	Optional	Start of season range (inclusive), e.g. 2020 for 'since 2020'
`season_to`	integer	Optional	End of season range (inclusive)
`season_type`	string	Optional	Filter by season type: REG (regular season) or POST (playoffs)Options: REG, POST

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_compare",
    "arguments": {
      "entity1": "Josh Allen",
      "entity2": "Patrick Mahomes",
      "season": 2024,
      "entity1_team": "BUF",
      "entity2_team": "KC"
    }
  }
}'

Example response

{
  "Josh Allen": {
    "passing": [
      {
        "season": 2024,
        "season_type": "POST",
        "attempts": 89,
        "completions": 58,
        "comp_pct": 65.2,
        "yards": 636,
        "touchdowns": 4,
        "interceptions": 0,
        "avg_epa": 0.242,
        "avg_cpoe": 8.954,
        "air_yards": 674,
        "avg_air_yards": 8.2
      },
      {
        "season": 2024,
        "season_type": "REG",
        "attempts": 497,
        "completions": 307,
        "comp_pct": 61.8,
        "yards": 3731,
        "touchdowns": 28,
        "interceptions": 6,
        "avg_epa": 0.262,
        "avg_cpoe": 0.844,
        "air_yards": 4022,
        "avg_air_yards": 8.3
      }
    ],
    "rushing": [
      {
        "season": 2024,
        "season_type": "POST",
        "carries": 27,
        "yards": 107,
        "yards_per_carry": 4,
        "touchdowns": 2,
        "fumbles_lost": 0,
        "avg_epa": 0.252,
        "explosive_runs": 2
      },
      {
        "season": 2024,
        "season_type": "REG",
        "carries": 94,
        "yards": 539,
        "yards_per_carry": 5.7,
        "touchdowns": 12,
        "fumbles_lost": 0,
        "avg_epa": 0.622,
        "explosive_runs": 17
      }
    ]
  },
  "Patrick Mahomes": {
    "passing": [
      {
        "season": 2024,
        "season_type": "POST",
        "attempts": 97,
        "completions": 55,
        "comp_pct": 56.7,
        "yards": 679,
        "touchdowns": 5,
        "interceptions": 2,
        "avg_epa": 0.014,
        "avg_cpoe": 0.486,
        "air_yards": 588,
        "avg_air_yards": 7.1
      },
      {
        "season": 2024,
        "season_type": "REG",
        "attempts": 617,
        "completions": 392,
        "comp_pct": 63.5,
        "yards": 3928,
        "touchdowns": 26,
        "interceptions": 11,
        "avg_epa": 0.109,
        "avg_cpoe": 2.563,
        "air_yards": 3682,
        "avg_air_yards": 6.4
      }
    ],
    "rushing": [
      {
        "season": 2024,
        "season_type": "POST",
        "carries": 16,
        "yards": 95,
        "yards_per_carry": 5.9,
        "touchdowns": 2,
        "fumbles_lost": 1,
        "avg_epa": 0.228,
        "explosive_runs": 4
      },
      {
        "season": 2024,
        "season_type": "REG",
        "carries": 38,
        "yards": 337,
        "yards_per_carry": 8.9,
        "touchdowns": 2,
        "fumbles_lost": 0,
        "avg_epa": 0.903,
        "explosive_runs": 12
      }
    ],
    "receiving": [
      {
        "season": 2024,
        "season_type": "REG",
        "targets": 1,
        "receptions": 1,
        "yards": 2,
        "avg_yac": 3,
        "touchdowns": 0,
        "avg_epa": -0.403,
        "explosive_plays": 0
      }
    ]
  },
  "compare_type_inferred": "player"
}

All tools