Basic lookup2 credits

search_players

Find players by name, team, or position

When to use it

You have a name and need the GSIS id (and PFR/ESPN ids) to call the stat endpoints.

Parameters

Name	Type	Required	Description
query	string	yes	Player name or part of it
team	string	no	Filter by current team code
position	string	no	Filter by position (e.g. QB, RB, WR, TE, OL, DL, LB, DB)
active	boolean	no	Default true, but an active-only search that finds nobody automatically falls back to all players and says so. Set false to search everyone outright.
limit	integer	no	Max results (default 10)

Request

bash

curl -X POST https://football-mcp-production.up.railway.app/v1/search_players \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
  "query": "Mahomes"
}'

Over MCP, ask for it in plain English and the client calls search_players itself. Point any MCP client at https://football-mcp-production.up.railway.app/mcp?key=YOUR_API_KEY.

Response

json

{
  "players": [
    {
      "player_id": "00-0033873",
      "name": "Patrick Mahomes",
      "position": "QB",
      "position_group": "QB",
      "team": "KC",
      "jersey_number": "15",
      "status": "ACT",
      "active": true,
      "rookie_season": 2017,
      "last_season": 2026,
      "college": "Texas Tech",
      "headshot": "https://static.www.nfl.com/image/upload/f_auto,q_auto/league/wdckwtob1lybvkmxnf7p",
      "pfr_id": "MahoPa00",
      "espn_id": "3139477"
    }
  ],
  "count": 1,
  "included_inactive": false
}

Response fields

Field	Type	Description
players[]	array	List of objects
players[].player_id	string
players[].name	string
players[].position	string
players[].position_group	string
players[].team	string
players[].jersey_number	string
players[].status	string
players[].active	boolean
players[].rookie_season	number
players[].last_season	number
players[].college	string
players[].headshot	string
players[].pfr_id	string
players[].espn_id	string
count	number
included_inactive	boolean