# College Football Data — how to use (mcp.ai)

Connect your College Football Data account and use 56 tools for analytics straight from your AI agent. Connect with your own API key. CollegeFootballData.com provides comprehensive college football data, including game scores, statistics, and recruiting information, accessible via a RESTful API.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_college_football_data?ms=1787291400000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `college_football_data_advanced_box_score`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/college_football_data`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/college_football_data/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/college_football_data/advanced/box/score` — Retrieves advanced analytics for a single college football game including: - Team metrics: PPA (Predicted Points Added), success rates, rushing efficiency, havoc rates, scoring opportunities - Player 
  - body: { gameId: integer }
- `POST https://api.mcp.ai/api/college_football_data/advanced/game/stats` — Tool to retrieve advanced team metrics at the game level. Use when detailed offensive and defensive metrics (success rates, explosiveness, havoc) are needed.
  - body: { team?: string, week?: integer, year?: integer, opponent?: string, seasonType?: string, excludeGarbageTime?: boolean }
- `POST https://api.mcp.ai/api/college_football_data/advanced/season/stats/team` — Retrieve advanced season-level team statistics including PPA (Predicted Points Added), success rates, explosiveness, havoc metrics, and rushing/passing efficiency breakdowns. Use this for in-depth tea
  - body: { team?: string, year?: integer, endWeek?: integer, startWeek?: integer, excludeGarbageTime?: boolean }
- `POST https://api.mcp.ai/api/college_football_data/betting/lines` — Tool to fetch betting lines and totals by game and provider. Use when you need current or historical betting line data filtered by specific criteria.
  - body: { away?: string, home?: string, team?: string, week?: integer, year?: integer, gameId?: integer, conference?: string, seasonType?: string }
- `POST https://api.mcp.ai/api/college_football_data/composite/team/talent` — Fetches 247Sports composite team talent rankings for a given season. Returns a list of all FBS teams ranked by their composite talent score, which is based on aggregate recruit ratings. Higher scores 
  - body: { year: integer }
- `POST https://api.mcp.ai/api/college_football_data/conference/memberships/history` — Tool to retrieve current conference memberships for college football teams. Returns which teams belong to which conference, optionally filtered by conference. Use to find all teams in a specific confe
  - body: { conference?: string }
- `POST https://api.mcp.ai/api/college_football_data/divisions/by/conference` — Tool to list FBS/FCS conference divisions with active years and metadata. Use after specifying an optional season year to filter active divisions.
  - body: { year?: integer }
- `POST https://api.mcp.ai/api/college_football_data/get/conference/sp` — Retrieve aggregated historical conference SP+ (Success Rate + Points Per Play) ratings for college football conferences. Use this to get conference-level offensive, defensive, and special teams metric
  - body: { year?: integer, conference?: string }
- `POST https://api.mcp.ai/api/college_football_data/get/drive/data` — Retrieves college football drive-level data including offensive/defensive teams, yards gained, drive results (TD, PUNT, INT, etc.), time elapsed, and scoring information. Use to analyze drive efficien
  - body: { team?: string, week?: integer, year: integer, defense?: string, offense?: string, conference?: string, seasonType?: string, defenseConference?: string, offenseConference?: string }
- `POST https://api.mcp.ai/api/college_football_data/get/field/goal/expected/points` — Retrieves field goal expected points values for various field positions and distances. Returns static model data showing expected points for field goal attempts based on distance. Useful for analyzing
- `POST https://api.mcp.ai/api/college_football_data/get/fpi` — Retrieves historical Football Power Index (FPI) ratings for college football teams. FPI is ESPN's measure that predicts team strength and game outcomes. Use this to get team ratings, efficiency metric
  - body: { team?: string, year?: integer, conference?: string }
- `POST https://api.mcp.ai/api/college_football_data/get/game/havoc/stats` — Tool to retrieve havoc statistics aggregated by game. Use when you need game-level havoc metrics including DB havoc rate, front seven havoc rate, and total havoc events for offense and defense.
  - body: { team?: string, week?: integer, year?: integer, opponent?: string, seasonType?: string }
- `POST https://api.mcp.ai/api/college_football_data/get/game/media` — Retrieve broadcast information for college football games including TV channels, streaming platforms, and radio outlets. Use this to find where games are being broadcast. Returns information about the
  - body: { team?: string, week?: integer, year: integer, mediaType?: string, conference?: string, seasonType?: string }
- `POST https://api.mcp.ai/api/college_football_data/get/games/and/results` — Tool to retrieve college American football games and results for a given season/week/team. Use when you need game schedules or outcomes filtered by specific criteria. Covers NCAA only; NFL and other s
  - body: { id?: integer, away?: string, home?: string, team?: string, week?: integer, year: integer, conference?: string, seasonType?: string }
- `POST https://api.mcp.ai/api/college_football_data/get/play/types` — Tool to fetch all available play types. Use when you need a catalog of play types for filtering or referencing play data.
- `POST https://api.mcp.ai/api/college_football_data/get/player/game/stats` — Fetches detailed player statistics for college football games. Returns individual player stats (passing, rushing, receiving, defensive, kicking, etc.) organized by game and team. Use cases: - Get QB p
  - body: { team?: string, week?: integer, year: integer, gameId?: integer, category?: string, conference?: string, seasonType?: string }
- `POST https://api.mcp.ai/api/college_football_data/get/player/usage` — Retrieves player usage data for a given season. Returns usage percentages across different play situations (overall, passing, rushing, by down, etc.). Use this to analyze how frequently players are in
  - body: { team?: string, year: integer, playerId?: integer, position?: string, conference?: string, excludeGarbageTime?: boolean }
- `POST https://api.mcp.ai/api/college_football_data/get/predicted/points/added/by/team` — Tool to retrieve historical team Predicted Points Added (PPA) metrics by season. Use when you need season-level PPA performance data for teams to analyze offensive and defensive efficiency across play
  - body: { team?: string, year?: integer, conference?: string, excludeGarbageTime?: boolean }
- `POST https://api.mcp.ai/api/college_football_data/get/pregame/win/probabilities` — Tool to retrieve pregame win probabilities for college football games. Use when you need predictive data about game outcomes before they are played, filtered by season, week, or team.
  - body: { team?: string, week?: integer, year?: integer, seasonType?: string }
- `POST https://api.mcp.ai/api/college_football_data/get/recruits` — Retrieves player recruiting rankings from the College Football Data API. Returns detailed information about high school, prep school, and junior college recruits including star ratings, composite rati
  - body: { team?: string, year?: integer, state?: string, position?: string, classification?: string }
- `POST https://api.mcp.ai/api/college_football_data/get/stats/categories` — Tool to fetch all available team statistical categories. Use when you need to discover valid category names for statistical analysis or filtering team stats.
- `POST https://api.mcp.ai/api/college_football_data/get/team/game/stats` — Fetch team-level box score statistics for college football games. Returns detailed game stats including offense (rushing/passing yards, TDs, turnovers), defense (tackles, sacks, interceptions), and sp
  - body: { team?: string, week?: integer, year: integer, gameId?: integer, conference?: string, seasonType?: string }
- `POST https://api.mcp.ai/api/college_football_data/get/team/recruiting/rankings` — Retrieve team recruiting rankings from the College Football Data API. Returns composite recruiting rankings based on recruit star ratings and commitments. Use to compare recruiting success across team
  - body: { team?: string, year?: integer }
- `POST https://api.mcp.ai/api/college_football_data/get/teams/ats` — Tool to retrieve against-the-spread (ATS) summary by team. Use when you need historical betting performance data showing how teams performed relative to point spreads.
  - body: { team?: string, year: integer, conference?: string }
- `POST https://api.mcp.ai/api/college_football_data/get/user/info` — Retrieves information about the authenticated user from the College Football Data API. Returns the user's Patreon subscription level and remaining API calls for rate limit monitoring. Use this to chec
- `POST https://api.mcp.ai/api/college_football_data/get/win/probability` — Tool to query play-by-play win probabilities for a specific game. Use when you need detailed probability metrics showing how win likelihood changed throughout the game.
  - body: { gameId: integer }
- `POST https://api.mcp.ai/api/college_football_data/list/coaches/and/history` — Tool to get coaching records and history. Use when you need coaches’ season-by-season data with optional filters.
  - body: { team?: string, year?: integer, maxYear?: integer, minYear?: integer, lastName?: string, firstName?: string }
- `POST https://api.mcp.ai/api/college_football_data/list/conferences` — Retrieves all college football conferences from the College Football Data API. Returns conferences across all NCAA divisions (FBS, FCS, Division II, Division III). Use this to get conference IDs for f
- `POST https://api.mcp.ai/api/college_football_data/list/fbs/teams` — Tool to list FBS teams for a given season. Use after selecting the season year to retrieve all FBS teams.
  - body: { year?: integer }
- `POST https://api.mcp.ai/api/college_football_data/list/fcs/teams` — Tool to list FCS teams for a given season and conference. Use when you need a list of FCS programs filtered by season year and conference.
  - body: { year?: integer, conference?: string }
- `POST https://api.mcp.ai/api/college_football_data/list/teams` — Retrieve a list of college football teams from the CFBD (College Football Data) API. Use this action to: - Get all college football teams (call with no parameters) - Get teams from a specific season (
  - body: { year?: integer, conference?: string }
- `POST https://api.mcp.ai/api/college_football_data/list/venues/stadiums` — Tool to list college football venues with metadata (name, capacity, location, etc.). Use when you need detailed venue information for a specific season.
  - body: { year?: integer }
- `POST https://api.mcp.ai/api/college_football_data/nfl/draft/picks` — Tool to list NFL Draft picks. Use when you need draft pick data by year, round, team, player, etc.
  - body: { pick?: integer, team?: string, year: integer, limit?: integer, round?: integer, offset?: integer, school?: string, overall?: integer, position?: string, conference?: string }
- `POST https://api.mcp.ai/api/college_football_data/nfl/draft/positions` — Retrieves the standardized list of NFL draft positions. Returns all position names and abbreviations used to classify players in NFL drafts. Useful for filtering draft picks by position or understandi
- `POST https://api.mcp.ai/api/college_football_data/nfl/draft/teams` — Tool to list NFL teams used in draft endpoints. Use when preparing to retrieve NFL draft data by team.
- `POST https://api.mcp.ai/api/college_football_data/play/by/play/data` — Tool to fetch play-by-play data for college football games. Use when you need detailed play logs filtered by season, week, team, or game.
  - body: { team?: string, week: integer, year: integer, gameId?: integer, defense?: string, offense?: string, playType?: string, conference?: string, seasonType?: string, defenseConference?: string, offenseConference?: string }
- `POST https://api.mcp.ai/api/college_football_data/play/stat/types` — Tool to fetch all play-level stat type definitions. Use when you need a catalog of available play stat types for filtering or referencing.
- `POST https://api.mcp.ai/api/college_football_data/play/stats/player` — Fetch player-level statistics tied to individual plays. Returns detailed stats for each player's contribution to a play (rushes, receptions, completions, etc.). Use this when you need: - Play-by-play 
  - body: { team?: string, week?: integer, year?: integer, gameId?: integer, athleteId?: integer, seasonType?: string, statTypeId?: integer }
- `POST https://api.mcp.ai/api/college_football_data/ppa/player/by/game/action` — Retrieve player-level PPA (Predicted Points Added) / EPA (Expected Points Added) stats for individual games. PPA measures how many points a player adds/subtracts compared to average performance on sim
  - body: { team?: string, week?: integer, year?: integer, playerId?: integer, position?: string, threshold?: string, excludeGarbageTime?: boolean }
- `POST https://api.mcp.ai/api/college_football_data/ppa/player/by/season` — Tool to fetch player-level PPA/EPA aggregated by season. Use when you need seasonal PPA metrics for specific players or groups after applying filters.
  - body: { team?: string, year?: integer, playerId?: integer, position?: string, threshold?: string, conference?: string, excludeGarbageTime?: boolean }
- `POST https://api.mcp.ai/api/college_football_data/ppa/predicted/points/ep` — Get expected points (EP) for all field positions given a specific down and distance scenario. Returns expected points values for yard lines 1-99, useful for analyzing game situations and fourth-down d
  - body: { down: integer, distance: integer }
- `POST https://api.mcp.ai/api/college_football_data/ppa/team/by/game` — Tool to retrieve team Predicted Points Added (PPA) by game. Use when you need team-level PPA metrics for games after filtering by season, week, team, or date.
  - body: { team?: string, week?: integer, year: integer, endDate?: string, startDate?: string, conference?: string, seasonType?: string }
- `POST https://api.mcp.ai/api/college_football_data/rankings/polls` — Retrieve college football poll rankings (AP Top 25, Coaches Poll, Playoff Committee, FCS, Division II/III). Returns weekly rankings including team rank, school name, conference, first-place votes, and
  - body: { week?: integer, year: integer, season_type?: string }
- `POST https://api.mcp.ai/api/college_football_data/ratings/elo` — Tool to retrieve Elo ratings for college football teams. Use when you need historical Elo ratings by season or for a specific team.
  - body: { team?: string, year?: integer }
- `POST https://api.mcp.ai/api/college_football_data/ratings/sp/plus` — Retrieve SP+ (Success Rate + Points Per Play) team ratings for college football. SP+ is an advanced tempo- and opponent-adjusted measure of college football efficiency. Use this to get overall team ra
  - body: { team?: string, year?: integer }
- `POST https://api.mcp.ai/api/college_football_data/ratings/srs` — Retrieves Simple Rating System (SRS) team ratings. SRS measures team strength based on point differential adjusted for strength of schedule. Either year or team parameter must be provided. Use year to
  - body: { team?: string, year?: integer, conference?: string }
- `POST https://api.mcp.ai/api/college_football_data/recruiting/group/dictionary` — Retrieves aggregated college football recruiting data grouped by position. Use this tool to analyze recruiting performance by position group for specific teams or conferences. Returns composite rating
  - body: { team?: string, endYear?: integer, startYear?: integer, conference?: string }
- `POST https://api.mcp.ai/api/college_football_data/recruiting/transfer/portal` — Retrieves NCAA college football transfer portal entries for a given season. Returns player transfer information including origin school, destination school (if committed), position, star rating, trans
  - body: { year: integer }
- `POST https://api.mcp.ai/api/college_football_data/returning/production/team` — Tool to fetch Bill Connelly–style returning production splits by team and season. Use when evaluating returning offense, defense, and overall production for teams in a given season.
  - body: { team?: string, year?: integer, conference?: string }
- `POST https://api.mcp.ai/api/college_football_data/search/players` — Search for college football players by name. Returns top 100 results matching the search term. Use this action to find players by name and optionally filter by year, team, or position.
  - body: { team?: string, year?: integer, position?: string, searchTerm: string }
- `POST https://api.mcp.ai/api/college_football_data/season/stats/player` — Fetch aggregated season statistics for college football players. Returns individual player stats by category (passing, rushing, receiving, defensive, kicking, etc.) for a specified year. Useful for co
  - body: { team?: string, year: integer, endWeek?: integer, category?: string, startWeek?: integer, conference?: string, seasonType?: string }
- `POST https://api.mcp.ai/api/college_football_data/season/stats/team` — Tool to get basic season stats aggregated by team and season. Use when you need a summary of team-level statistics for a particular season.
  - body: { team?: string, year: integer, endWeek?: integer, startWeek?: integer, conference?: string, seasonType?: string }
- `POST https://api.mcp.ai/api/college_football_data/season/types/dictionary` — Retrieve the list of available season types for a specific college football year. Returns types like 'regular', 'postseason', and for certain years 'spring_regular', 'spring_postseason'. Use this to d
  - body: { year: integer }
- `POST https://api.mcp.ai/api/college_football_data/team/matchup/history` — Tool to retrieve head-to-head team matchup records over a date range. Use after selecting two FBS teams to compare their matchup history.
  - body: { team1: string, team2: string, maxYear?: integer, minYear?: integer }
- `POST https://api.mcp.ai/api/college_football_data/team/records` — Retrieve college football team win-loss records for a specific season. Returns detailed breakdowns including total, conference, home, away, neutral site, regular season, and postseason records. Requir
  - body: { team?: string, year: integer, limit?: integer, offset?: integer, division?: string, conference?: string, seasonType?: string }
- `POST https://api.mcp.ai/api/college_football_data/team/roster` — Fetches the roster for a college football team for a specific season. Returns player details including name, position, height, weight, jersey number, academic year, and hometown info. Use this to get 
  - body: { team: string, year: integer }

## Example prompts
- "What can I do in College Football Data?"
- "Show me a summary of my College Football Data account"

## More
- Page: https://mcp.ai/college_football_data
- Agent spec (llms.txt): https://mcp.ai/college_football_data/llms.txt
- Postman collection: https://mcp.ai/college_football_data/postman.json