io.github.chrischall/maxpreps-mcp
MaxPreps MCP — high school schedules, scores, records, rosters and stat leaders
Open source Open in the app JSON README (API)
About
MaxPreps MCP — high school schedules, scores, records, rosters and stat leaders
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- chrischall
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.3.0
- Last push
- 2026-09-05T17:34:18Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:02:34
- Updated
- 2026-09-04 23:00:30
- Origin id
io.github.chrischall/maxpreps-mcp
README
# maxpreps-mcp
MCP server for [MaxPreps](https://www.maxpreps.com) — 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
```bash
npx maxpreps-mcp
```
Or add it to an MCP host:
```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:
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
```bash
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