maxpreps-mcp

MCP server for MaxPreps — read any US high school's team schedules, scores, records, rosters, stat leaders and athlete careers.

Developed and maintained by AI (Claude Code). Use at your own discretion.

No account, no API key, no browser extension. MaxPreps serves its pages with Next.js, and every public page has a companion JSON route carrying the same data the page was rendered from. This server reads those routes directly over plain HTTPS, so it works anywhere Node runs.

Install

npx maxpreps-mcp

Or add it to an MCP host:

{
  "mcpServers": {
    "maxpreps": {
      "command": "npx",
      "args": ["-y", "maxpreps-mcp"]
    }
  }
}

Tools

All fifteen are read-only; this server has no write path.

Tool	What it does
maxpreps_search	Find a school or athlete by name — start here
maxpreps_list_teams	Every team path a school publishes, with sport/gender/level
maxpreps_get_school	School profile, identifiers, association, nearby schools
maxpreps_get_team	Season record, standings, rankings, and available seasons
maxpreps_get_schedule	Games with results and scores, plus a computed record
maxpreps_get_roster	Players with jersey, class, positions, height, weight
maxpreps_get_stat_leaders	Statistical leaders with qualifying minimums
maxpreps_get_rankings	Ranked leaderboard for a sport, national or by state
maxpreps_get_team_rankings	Where one team ranks nationally, by state, division, metro
maxpreps_get_standings	Conference table with every team's record
maxpreps_list_stat_categories	Which stat leaderboards exist, and their paths
maxpreps_get_stat_leaderboard	Ranked athletes for one stat, statewide or national
maxpreps_get_athlete	One athlete's career page
maxpreps_healthcheck	Connectivity plus site build-id resolution
maxpreps_get_page	Raw page data for anything the above doesn't cover

Typical flow

Paths are not guessable, so resolve before you fetch:

1. maxpreps_search "myers park" → the school's canonicalUrl
2. maxpreps_list_teams on that path → real team paths
3. maxpreps_get_schedule / _roster / _stat_leaders / _standings on a team path

To go the other way — discovering teams and athletes rather than looking one up — maxpreps_get_rankings and maxpreps_get_stat_leaderboard return ranked lists whose entries each carry a teamPath you can feed straight back in. Stat leaderboard paths are not guessable either, so list the categories first.

Prior seasons are a season argument ("25-26"); roughly 20 years are available.

Configuration

Everything is optional — the server works with no configuration at all.

Variable	Default	Purpose
MAXPREPS_USER_AGENT	built-in	Override the User-Agent sent to MaxPreps
MAXPREPS_CACHE_TTL	300	Seconds to reuse a fetched page; 0 disables
MAXPREPS_MIN_INTERVAL_MS	250	Minimum spacing between requests
MAXPREPS_TIMEOUT_MS	20000	Per-request timeout

Things worth knowing

These are properties of MaxPreps' data, and each one has bitten a naive reading:

• Scores are winner-first in the raw data. MaxPreps renders a loss as "L 20-13" even when the team scored 13. The teamScore / opponentScore fields this server returns are always oriented team-vs-opponent.
• Rosters and schedules carry hidden rows. A meaningful minority are flagged deleted and the site does not render them — the 2025-26 Myers Park football roster has 87 entries behind 63 visible players. They are excluded by default.
• An out-of-season team is not a broken one. Before opening day the current season legitimately has an empty roster and no results; ask for a prior season.
• Search is literal. "myers park" finds the school; "myers park high" finds nothing. Drop qualifiers before concluding a school is absent.
• Statewide scoreboards aren't available. /<st>/<sport>/scores/ renders its game list client-side from a route that has no server-rendered payload. Per-team schedules are the supported way to get scores; maxpreps_get_rankings is the way to see a whole state's teams at once.

Shell-only alternative

The repo also ships a maxpreps skill (skills/maxpreps/) that reaches the same data through curl + a small decoder, with no server to run. If you only ever use Claude Code on one machine, the skill alone may be all you need; the MCP server is what makes this reachable from claude.ai, a phone, or any other client.

Development

npm install
npm run build
npm test

docs/MAXPREPS-API.md pins the captured request/response shapes, the positional key maps, and how to re-derive them if MaxPreps changes its bundle.

Etiquette

This reads an undocumented surface on someone else's site on behalf of one user. Requests are spaced and responses cached by default. Please keep it that way.

License

MIT