Documentation menu

nfl_search_plays

Free tier

Play finder

PREFERRED for finding specific plays. Search by player, team, season, week, play type, situation, touchdowns, turnovers, or minimum yards. Returns plays sorted by impact (EPA). Set group_by to rank players (passer/rusher/receiver/scorer) by play, touchdown, and yard counts instead of listing individual plays. Use this instead of nfl_query whenever looking for plays.

Minimum tier: Free
Data coverage: Varies by query

Parameters

Name	Type	Required	Description
`team`	string	Optional	Offensive team abbreviation (e.g. KC, PHI, BUF)
`opponent`	string	Optional	Defensive team abbreviation
`player`	string	Optional	Player name — full ('Justin Jefferson') or short ('J.Jefferson') both accepted.
`season`	integer	Optional	Exact season year (2013–2025). Use season_from/season_to for ranges.
`season_from`	integer	Optional	Start of season range (inclusive), e.g. 2020 for 'since 2020'
`season_to`	integer	Optional	End of season range (inclusive)
`week`	integer	Optional	Week number (1–22)
`season_type`	string	Optional	Filter by season type: REG (regular season) or POST (playoffs)Options: REG, POST
`play_type`	string	Optional	Type of playOptions: pass, run, field_goal, punt, kickoff
`situation`	string	Optional	Game situation filterOptions: red_zone, third_down, fourth_down, two_minute
`is_touchdown`	boolean	Optional	Only touchdown plays
`is_turnover`	boolean	Optional	Only turnover plays (INT or fumble lost)
`min_yards`	integer	Optional	Minimum yards gained
`max_rows`	integer	Optional	Max results (default 50, max 500)Default: 50
`group_by`	string	Optional	Aggregate the filtered plays per player instead of returning individual plays: play count, touchdowns, yards, and average EPA, ranked by play count. 'scorer' groups by the touchdown scorer.Options: passer, rusher, receiver, scorer

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_search_plays",
    "arguments": {
      "player": "Justin Jefferson",
      "season": 2024,
      "is_touchdown": true,
      "max_rows": 5
    }
  }
}'

Example response

Excerpt · lists trimmed

{
  "rows": [
    {
      "season": 2024,
      "week": 2,
      "posteam": "MIN",
      "defteam": "SF",
      "down": 2,
      "ydstogo": 9,
      "play_type": "pass",
      "yards_gained": 97,
      "epa": 7.665,
      "desc": "(9:51) 14-S.Darnold pass deep middle to 18-J.Jefferson for 97 yards, TOUCHDOWN.",
      "passer_player_name": "S.Darnold",
      "rusher_player_name": null,
      "receiver_player_name": "J.Jefferson",
      "touchdown": 1,
      "interception": 0
    },
    {
      "season": 2024,
      "week": 14,
      "posteam": "MIN",
      "defteam": "ATL",
      "down": 3,
      "ydstogo": 8,
      "play_type": "pass",
      "yards_gained": 52,
      "epa": 5.64,
      "desc": "(3:36) (Shotgun) 14-S.Darnold pass deep right to 18-J.Jefferson for 52 yards, TOUCHDOWN.",
      "passer_player_name": "S.Darnold",
      "rusher_player_name": null,
      "receiver_player_name": "J.Jefferson",
      "touchdown": 1,
      "interception": 0
    },
    {
      "season": 2024,
      "week": 1,
      "posteam": "MIN",
      "defteam": "NYG",
      "down": 4,
      "ydstogo": 2,
      "play_type": "pass",
      "yards_gained": 3,
      "epa": 3.913,
      "desc": "(6:58) (Shotgun) 14-S.Darnold pass short left to 18-J.Jefferson for 3 yards, TOUCHDOWN.",
      "passer_player_name": "S.Darnold",
      "rusher_player_name": null,
      "receiver_player_name": "J.Jefferson",
      "touchdown": 1,
      "interception": 0
    }
  ],
  "row_count": 5
}

All tools