Skip to main content
Glama
Sign In
maxpreps-mcp

maxpreps-mcp

by chrischall
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

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"]
    }
  }
}

Related MCP server: College Basketball Stats MCP Server

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:

  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

Available Tools

15 tools
maxpreps_get_athleteGet a MaxPreps athlete careerA
Read-onlyIdempotent

One athlete’s career page: season history, sports played, and available data. Pass the careerCanonicalUrl from maxpreps_search verbatim — it carries the required careerid parameter, without which the page cannot be addressed. Read-only.

Inputs: athlete (required), careerId.

maxpreps_get_pageGet raw MaxPreps page dataA
Read-onlyIdempotent

Escape hatch: return the raw server-rendered data for any public MaxPreps page, undecoded. Use when a dedicated tool does not cover what you need (playoff brackets, conference standings, article listings). Note that positional payloads — team rosters and schedules — arrive as bare arrays here with no field names; use maxpreps_get_roster / maxpreps_get_schedule for those. Roster rows (athleteData) are always projected to public roster fields (name, jersey, positions, class, height, weight). Read-only.

Inputs: path (required), keysOnly.

maxpreps_get_rankingsGet MaxPreps team rankingsA
Read-onlyIdempotent

Ranked leaderboard of teams for a sport — nationally, or within one state. Each entry carries the rank, rating, overall record, movement, and a teamPath ready to pass to the other team tools, so this is the way to discover teams rather than look one up. Results are paginated 25 at a time. Omitting season uses the current one, which is empty before that sport is under way. Read-only.

Inputs: sport (required), state, season, pageNumber.

maxpreps_get_rosterGet a MaxPreps team rosterA
Read-onlyIdempotent

Players on a team for one season: jersey, name, class year, positions, height and weight. Soft-deleted entries (duplicates and departed players the site hides) are excluded by default — a roster payload often carries substantially more rows than the page shows. Height and weight are null when the school did not publish them. Read-only.

Inputs: team (required), season, position, includeDeleted.

maxpreps_get_scheduleGet a MaxPreps team schedule and scoresA
Read-onlyIdempotent

Every game for a team season, with the result and both scores. Scores are oriented team-vs-opponent (teamScore/opponentScore); the raw resultString MaxPreps renders is winner-first, so a loss reads "L 20-13" even when the team scored 13. Soft-deleted contests are hidden by default, matching the site. Before opening day a current season legitimately has no results — check a prior season. Also returns any playoff or championship tournaments the season fed into. Read-only.

Inputs: team (required), played, season, includeDeleted, +1 more.

maxpreps_get_schoolGet a MaxPreps school profileA
Read-onlyIdempotent

School profile: identifiers, location, state athletic association, partner flags, plus nearby schools and recent articles/videos. Take the path from maxpreps_search. Read-only.

Inputs: school (required), includeNearby.

maxpreps_get_standingsGet conference standingsA
Read-onlyIdempotent

The standings table a team sits in — every team in the conference with its conference and overall records and placement, not just this team's own line (maxpreps_get_team gives that). Also returns the ranked statistical leaders MaxPreps highlights for the season. Read-only.

Inputs: team (required), season.

maxpreps_get_stat_leaderboardGet a MaxPreps stat leaderboardA
Read-onlyIdempotent

The ranked athletes for one statistical category across a state or nationally — up to 200 per board, each with their full stat line, school, and a teamPath for the other team tools. Take path from maxpreps_list_stat_categories rather than constructing it. If MaxPreps changes the row shape the rows are returned undecoded with a warning rather than mislabelled. Read-only.

Inputs: path (required), limit.

maxpreps_get_stat_leadersGet MaxPreps team stat leadersA
Read-onlyIdempotent

Statistical leaders for a team season — each entry names the athlete, the stat, its value and the athlete's career URL. Also returns the qualifying minimums and the stat refresh time. Coverage varies by sport and by how diligently the school reports; an empty result is normal, not an error. Read-only.

Inputs: team (required), season.

maxpreps_get_teamGet a MaxPreps team seasonA
Read-onlyIdempotent

Team overview for one season: sport/level/season identifiers, the win-loss record and points for/against, conference standing, rankings, and the full list of seasons this team has on MaxPreps (roughly 20 years). Use it to confirm a record without summing a schedule. Read-only.

Inputs: team (required), season, includeSeasons.

maxpreps_get_team_rankingsGet one team’s rankingsA
Read-onlyIdempotent

Where a single team sits in each ranking MaxPreps publishes for it — typically national, state, state division/class, and metro area — along with the teams ranked immediately around it. Use this for "how good is this team"; use maxpreps_get_rankings to browse a whole leaderboard. Read-only.

Inputs: team (required), season.

maxpreps_healthcheckCheck MaxPreps connectivityA
Read-only

Verify MaxPreps is reachable and that the site build id — which every data route embeds and which changes on each deploy — resolves. Also probes a real data route, so a pass means tools will work. Reports a failure rather than throwing. No credentials are required by this server. Read-only.

Inputs: no named parameters.

maxpreps_list_stat_categoriesList MaxPreps stat leaderboard categoriesA
Read-onlyIdempotent

Which statistical leaderboards exist for a sport, with the path to each one plus the national and in-scope averages and the games-played minimum. Call this before maxpreps_get_stat_leaderboard — the leaf path is not derivable from the stat name (Total TDs lives at touchdowns/tot-tds, Sacks at sacks/tot-sacks), so the path must come from here. Read-only.

Inputs: sport (required), state, season.

maxpreps_list_teamsList a school’s teamsA
Read-onlyIdempotent

Every team path a school publishes, with sport, gender and level. Call this before any team tool — the sport path segments are not guessable (the default gender varies by sport, so girls golf is "golf/girls" while boys golf is "golf/spring", and field hockey has no gender segment at all). Passing a team path instead of a school path returns that team’s seasons. Read-only.

Inputs: school (required), level, sport.

maxpreps_searchSearch MaxPreps schools and athletesA
Read-onlyIdempotent

Find a high school or an athlete by name. This is the entry point for every other tool: it returns each school's canonicalUrl (the site path the team tools need) and each athlete's careerCanonicalUrl. Search is exact-ish — prefer the plain school name ("myers park"), because appending qualifiers like "high" or "high school" usually returns nothing. Read-only.

Inputs: query (required), limit.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4.1/5.0

    Scored across 15 tools

    Disambiguation5/5

    Each tool targets a distinct resource or level of granularity: school, team, schedule, roster, athlete, standings, rankings, and stat leaderboards. Near neighbors are explicitly differentiated in the descriptions, such as get_standings vs get_team, get_rankings vs get_team_rankings, and get_stat_leaders vs get_stat_leaderboard. No two tools require semantic guessing.

    Naming Consistency4/5

    The maxpreps_ prefix with a get_ or list_ verb is applied consistently across almost all tools, making the pattern predictable. Minor deviations are maxpreps_search and maxpreps_healthcheck, which do not follow the verb_noun shape, and the subtle singular/plural pair stat_leaders vs stat_leaderboard.

    Tool Count5/5

    Fifteen tools is at the high end of the ideal range, but each one maps to a distinct data surface, including an operational healthcheck and an explicit escape hatch. The granularity is justified by MaxPreps' broad read-only domain rather than bloat.

    Completeness4/5

    The set covers core MaxPreps workflows: search, school profile, team discovery, schedule, roster, standings, stats, rankings, and athlete career pages. Minor gaps like playoff brackets, arbitrary conference standings, and article listings are left to the raw get_page escape hatch, so agents can work around them.

    Maintenance

    ActivityActive
    ResponsivenessUsually handled

    Resources

    Related MCP Connectors

    Related MCP Servers

    • MLB V3 Scores MCP Server

      ag2-mcp-servers
      F
      license
      Not graded
      quality
      D
      maintenance
      An MCP Server that enables interaction with MLB scores and statistics via the SportsData.io MLB V3 Scores API, allowing users to access baseball data through natural language queries.
      -

    • College Basketball Stats MCP

      ag2-mcp-servers
      F
      license
      Not graded
      quality
      D
      maintenance
      An MCP server for accessing college basketball statistics through the SportsData.io CBB v3 Stats API, enabling AI agents to retrieve and analyze college basketball data through natural language interactions.
      -

    • nba-mcp

      ufo2243
      A
      license
      A
      quality
      C
      maintenance
      MCP server for NBA live data and stats, providing read-only tools to query live scores, box scores, player info, standings, and more from NBA.com.
      15
      11 npm
      1
      MIT

    • SportRadar MCP Server

      srinayani-m
      F
      license
      Not graded
      quality
      D
      maintenance
      MCP server providing tools to query live scores, schedules, standings, and game stats from the SportRadar API for multiple sports including NFL, NBA, NHL, NCAAMB, soccer, and tennis.
      -