Alphaportal MCP server

alphaportal-mcp

An MCP server for AlphaPortal (AlphaRoute), the parent/guardian school-bus transportation portal used by districts such as Charlotte-Mecklenburg Schools (cmsnc.alphaportal.app). Ask Claude where your child's bus is, what stops they have, and what arrival notifications came in — and (confirm-gated) adjust notification preferences and walk-zone radius.

Developed and maintained by AI. Use at your own discretion.

What it can do

Reads (all live-verified against the real API):

• alphaportalliststudents — your children, with grade, school, and transport flags
• alphaportalgetstudent — a child's school plus morning/afternoon stops
• alphaportalgetstudent_stops — assigned stops with times and locations
• alphaportalgetbuslocation — live GPS of the bus** for the AM or PM run
• alphaportallistnotifications — arrival/departure alerts
• alphaportallistrequests — submitted transportation requests + tracking numbers
• alphaportalgetreport_link — a PDF report download link
• alphaportallistschools, alphaportallistgrades — district reference data
• alphaportalgetprofile, alphaportalgetaccount, alphaportalgetsettings
• alphaportalsessionstatus — is a working session configured (no secrets returned)

Writes (confirm-gated — a dry-run of the exact payload unless confirm: true):

• alphaportaleditwalk_radius — set a student's walk-zone radius (meters)
• alphaportalsetnotification — set per-student push/email notification preferences

Authentication — the refresh token

AlphaPortal's login is reCAPTCHA-gated and can't be automated with a username/password. Instead this server uses the refresh token the web app stores in your signed-in browser (an 8-day credential); from it, it mints the short-lived access tokens it needs entirely server-side — no browser bridge in the request hot path. There are two ways it gets that token, tried in order:

set, the server reads it once from your signed-in AlphaPortal tab via the Transporter browser extension (the fetchproxy bridge) — a one-shot read that snapshots only the token (a JSON-pointer extraction, so your name/email/ phone never leave the browser), then closes. Requires the extension installed and a signed-in .alphaportal.app tab. Set ALPHAPORTALDISABLE_FETCHPROXY=1 to turn this off.

1. Automatic (fetchproxy bootstrap). If ALPHAPORTALREFRESHTOKEN is not

signed-in tab's DevTools console:

1. Manual (env var). Set ALPHAPORTALREFRESHTOKEN yourself. Capture it in a

JSON.parse(localStorage.user).User.RefreshToken

This is the right path for a headless/hosted deployment with no browser.

Either way, the server persists each rotated refresh token, so the 8-day window rolls forward as long as you use it at least once every 8 days. If it expires, sign back in (path 1) or re-capture (path 2). The alphaportal-fpx skill under skills/ documents the same capture from a shell via the fpx CLI.

Setup

npm install
npm run build
echo 'ALPHAPORTAL_REFRESH_TOKEN=<paste the token>' > .env
node dist/index.js   # or wire it into your MCP host

.env is gitignored. For an MCP host, set ALPHAPORTALREFRESHTOKEN in its env block (.mcp.json / mcpb user config both reference it).

Optional environment variables

Hosting on mcp-host

Shortened. The full README is on GitHub.