maxpreps-mcp

maxpreps-mcp

适用于 MaxPreps 的 MCP 服务——读取美国任意高中的球队赛程、比分、战绩、阵容、统计数据领跑者和运动员生涯信息。

由 AI（Claude Code）开发和维护。请自行斟酌使用。

无需账号、API 密钥或浏览器扩展。 MaxPreps 使用 Next.js 提供页面，每个公开页面都有一个配套的 JSON 路由，包含渲染该页面所用的相同数据。本服务通过普通 HTTPS 直接读取这些路由，因此可在任何能运行 Node 的环境中使用。

安装

npx maxpreps-mcp

或者将其添加到 MCP 主机：

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

工具

全部十五个工具均为只读；本服务不提供写入功能。

工具	功能
maxpreps_search	按名称查找学校或运动员——从这里开始
maxpreps_list_teams	学校发布的所有球队路径，包含运动项目／性别／级别
maxpreps_get_school	学校简介、标识符、所属协会和附近学校
maxpreps_get_team	赛季战绩、排名、排行榜和可用赛季
maxpreps_get_schedule	比赛及其结果和比分，以及计算得出的战绩
maxpreps_get_roster	球员信息，包括球衣号码、年级、位置、身高和体重
maxpreps_get_stat_leaders	达到最低参赛要求的统计数据领跑者
maxpreps_get_rankings	某项运动的排名榜单，可按全国或州查看
maxpreps_get_team_rankings	某支球队在全国、州、分区和都会区的排名
maxpreps_get_standings	包含每支球队战绩的联盟积分榜
maxpreps_list_stat_categories	现有的统计排行榜及其路径
maxpreps_get_stat_leaderboard	某项统计数据的运动员排名，可按州或全国查看
maxpreps_get_athlete	某位运动员的生涯页面
maxpreps_healthcheck	连通性检查及网站 build-id 解析
maxpreps_get_page	获取上述工具未涵盖内容的原始页面数据（阵容行会映射为公开字段）

常见流程

路径无法猜测，因此请先解析，再获取数据：

1. maxpreps_search "myers park" → 学校的 canonicalUrl
2. 对该路径调用 maxpreps_list_teams → 获取真实球队路径
3. 对球队路径调用 maxpreps_get_schedule / _roster / _stat_leaders / _standings

反过来，如需发现球队和运动员，而不是查找特定对象，可使用 maxpreps_get_rankings 和 maxpreps_get_stat_leaderboard。它们会返回排名列表，其中每个条目都带有 teamPath，可直接传回工具使用。统计排行榜路径也无法猜测，因此请先列出类别。

较早的赛季可通过 season 参数指定（"25-26"）；目前约有 20 年的数据可用。

配置

所有配置均为可选项；即使完全不配置，本服务也能正常运行。

变量	默认值	用途
MAXPREPS_USER_AGENT	内置	覆盖发送给 MaxPreps 的 User-Agent
MAXPREPS_CACHE_TTL	300	重用已获取页面的秒数；0 表示禁用
MAXPREPS_MIN_INTERVAL_MS	250	请求之间的最小间隔
MAXPREPS_TIMEOUT_MS	20000	每个请求的超时时间

值得了解的事项

以下是 MaxPreps 数据的一些特性，稍有疏忽就容易误读：

• 原始数据中的比分将获胜方列在前面。 即使球队得了 13 分，MaxPreps 也会将失利显示为 "L 20-13"。此服务返回的 teamScore / opponentScore 字段始终按球队与对手的顺序排列。
• 名单和赛程中包含隐藏行。 其中有相当一部分被标记为已删除，网站不会显示这些内容——2025-26 赛季 Myers Park 橄榄球队名单有 87 条记录，但只显示 63 名球员。默认会排除这些记录。
• 赛季外的球队并非数据有误。 开赛前，当前赛季的名单为空且没有比赛结果是正常情况；请查询往年赛季。
• 搜索是精确匹配。 "myers park" 能找到学校；"myers park high" 则找不到。断定学校不存在之前，请先删去限定词。
• 无法获取全州比分列表。 /<st>/<sport>/scores/ 会在客户端根据一个没有服务端渲染数据的路由生成比赛列表。获取比分时，请使用受支持的各队赛程；要一次查看某州的所有球队，请使用 maxpreps_get_rankings。

仅使用 Shell 的替代方案

此代码库还提供了一个 maxpreps 技能（skills/maxpreps/），通过 curl 和一个小型解码器获取相同的数据，无需运行服务。如果你只在一台机器上使用 Claude Code，可能只需要这个技能；MCP 服务则让你可以从 claude.ai、手机或其他客户端访问这些数据。

开发

npm install
npm run build
npm test

docs/MAXPREPS-API.md 记录了捕获的请求／响应结构、位置键映射，以及 MaxPreps 更改其 bundle 后如何重新推导这些内容。

使用须知

此工具代表一名用户读取他人网站上未公开说明的接口。默认情况下，请求之间会留出间隔，并缓存响应。请保持这一设置。

许可证

MIT