Schoolpass MCP README

schoolpass-mcp

MCP server for SchoolPass — read AND change your child's school arrival & dismissal from a parent account. Talks to the SchoolPass REST API used by the SchoolPass web and mobile apps, authenticating server-side with your own parent email and password (no browser, no extension).

Developed and maintained by AI (Claude Code). Use at your own discretion.

Parent-scoped: read tools plus a confirm-gated dismissal-change write/cancel.

Tools

Tool	What it does
`schoolpass_healthcheck`	Reachability + authentication, reported separately.
`schoolpass_whoami`	The parent identity the server signed in as.
`schoolpass_list_students`	Your linked students — name, grade, home dismissal location, aftercare.
`schoolpass_get_profile`	The parent account profile.
`schoolpass_list_drivers`	Authorized pickup drivers; `include_carpool: true` adds their carpools (other families' contact/vehicle fields dropped unless `view: "full"`).
`schoolpass_get_calendar`	A student's arrival/dismissal calendar over a date range.
`schoolpass_list_pickup_changes`	Pickup/dismissal changes for a student on a date.
`schoolpass_list_dismissal_locations`	The school's dismissal locations, with ids.
`schoolpass_get_school_info`	Basic school info and per-school config.
`schoolpass_submit_dismissal_change`	Submit a dismissal/arrival change (confirm-gated: preview + single-use `confirmToken`).
`schoolpass_cancel_dismissal_change`	Cancel a change, back to default (confirm-gated: preview + `confirmToken`).

Configuration

Env var	Required	Notes
`SCHOOLPASS_EMAIL`	yes	Your SchoolPass parent account email.
`SCHOOLPASS_PASSWORD`	yes	Your SchoolPass password.
`SCHOOLPASS_SCHOOL_CODE`	yes	The numeric school id (the `AppCode` / `appCode` value; e.g. `1183`).
`SCHOOLPASS_API_HOST`	no	Regional API host override (default `busapi-east16-ss.school-pass.net`). Must be an https `*.school-pass.net` host — the password is sent there, so `http://` or any other domain is refused.
`SCHOOLPASS_TIMEZONE`	no	The school's IANA timezone (e.g. `America/New_York`), used for the "today" default of the calendar and pickup-change reads. Defaults to the server's local zone; set it when the server runs elsewhere (a hosted server runs in UTC, so evening defaults would otherwise point at tomorrow).
`MCP_CONFIRM_MODE`	no	How the two writes confirm on a client that cannot show a prompt: `ask-user` (default — preview + token, the user approves in chat), `auto` (the model may use the token after reviewing the preview), or `refuse`.
`MCP_CONFIRM_ELICITATION`	no	`off` never shows a confirmation prompt, so every client gets the `MCP_CONFIRM_MODE` behaviour. Set it for a client that says it can show prompts but never does (the write hangs — opencode 2.0.x). Default `on`; any other value is treated as `on`, with a warning on stderr.
`MCP_CONFIRM_TTL_SECONDS`	no	How long a confirm token stays valid (default `600`).
`MCP_CONFIRM_SECRET`	no	HMAC key for confirm tokens; set only if tokens must survive a restart. On mcp-host the host supplies a stable per-child key (`MCP_HOST_CONFIRM_SECRET`) and spent tokens are recorded under `MCP_DATA_DIR`, so an approval survives an idle restart.

Finding your school id and region host: sign into your school's <school>.school-pass.net portal, open the new SchoolPass app, and read appCode (the id) and apiUrl (the host) from its browser localStorage.

Install

config.json

{
  "mcpServers": {
    "schoolpass": {
      "command": "npx",
      "args": ["-y", "schoolpass-mcp"],
      "env": {
        "SCHOOLPASS_EMAIL": "you@example.com",
        "SCHOOLPASS_PASSWORD": "your-password",
        "SCHOOLPASS_SCHOOL_CODE": "1183"
      }
    }
  }
}

Notes

Parent scope only. A parent token cannot reach admin routes (visitor management, carline operations, reports, bus routing); those return 403.
Never retry a rejected login. SchoolPass fronts its login with reCAPTCHA; repeated failures can get the account challenged. A password SchoolPass refuses (400/401) is tried once per process: later calls return the same error without contacting SchoolPass until the configured credentials change or the server restarts. A CDN/WAF block page (CloudFront, Cloudflare, …) is not a refusal: it is reported as an edge block, never latched, and never spends or discards the stored session.
No credentials, still boots. The server starts without configuration and answers tools/list; the config error surfaces on the first tool call.

Without the server: `curl`

The SchoolPass API is reachable server-side, so a one-off shell read needs no MCP process — see the bundled schoolpass-curl skill (skills/schoolpass-curl/) for a curl + jq recipe set.

Development

Terminal

npm install
npm test            # tsc typecheck + unit + boot tests
npm run build       # tsc + esbuild bundle
node --env-file=.env scripts/live-check.mjs   # live read-only check (needs .env)

License

MIT