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

Terminal

npx maxpreps-mcp

Or add it to an MCP host:

config.json

{
  "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:

maxpreps_search "myers park" → the school's canonicalUrl
maxpreps_list_teams on that path → real team paths
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

Terminal

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