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
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 (roster rows are projected to public fields) |
Typical flow
Paths are not guessable, so resolve before you fetch:
maxpreps_search "myers park" → the school's canonicalUrlmaxpreps_list_teams on that path → real team pathsmaxpreps_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