gradebook-mcp

ParentVUE shows grades one student, term, and course at a time. That makes a simple question—“What schoolwork needs attention?”—surprisingly hard to answer, especially for families with more than one child.

gradebook-mcp solves that problem by syncing ParentVUE into a local, read-only SQLite snapshot. You can access it through either interface—or both:

• a phone-friendly dashboard for reading grades, assignments, and consolidated missing work; and

• an optional MCP server so AI assistants can answer questions about the same data.

Despite the package name, MCP is not required. The dashboard runs on its own without an MCP endpoint or MCP authentication.

It never writes to ParentVUE. Data stays on your machine, and automatic sync is off until you explicitly enable it.

Quick start

Requirements: Docker with Compose and a ParentVUE parent account. The image is published for linux/amd64 and linux/arm64, so no checkout or build is needed. In an empty directory, download the Compose file and the settings template:

curl -fsSLO https://raw.githubusercontent.com/songsterq/gradebook-mcp/main/compose.yaml
curl -fsSL -o .env https://raw.githubusercontent.com/songsterq/gradebook-mcp/main/.env.example

Choose the interfaces you want to run:

• Dashboard only: set UI_PORT and leave PORT blank. No MCP setup or authentication is needed.

• MCP only: set PORT and configure one MCP authentication mode.

• Both: set both ports and configure MCP authentication.

To run both interfaces, generate a token with openssl rand -hex 32, then edit .env and set:

GRADEBOOK_PARENTVUE_HOST=<district>.edupoint.com
GRADEBOOK_PARENTVUE_USER=you@example.com
GRADEBOOK_PARENTVUE_PASS=...

# Protect the MCP endpoint with one of the auth modes below.
MCP_BEARER_TOKEN=<random token>

# Enable the dashboard.
UI_PORT=3001

Start the service:

docker compose up -d
curl http://127.0.0.1:3000/healthz

• MCP endpoint: http://127.0.0.1:3000/mcp

• Dashboard: http://127.0.0.1:3001/gradebook

Run the first sync with the dashboard's Sync now button or the gradebook_sync MCP tool.

Dashboard only

If you do not need MCP, leave PORT and all MCP authentication settings blank, set UI_PORT=3001, and run (requires Compose v2.24 or newer):

curl -fsSLO https://raw.githubusercontent.com/songsterq/gradebook-mcp/main/compose.dashboard-only.yaml
docker compose -f compose.yaml -f compose.dashboard-only.yaml up -d

The dashboard is unauthenticated. Keep it on a trusted LAN, VPN, or private overlay network such as Tailscale; never expose it to the public Internet.

Related MCP server: canvas-scholar-mcp

Optional MCP tools

The MCP server exposes eight tools:

Start with gradebook_missing for action items or gradebook_overview to find student (stu_...) and course (crs_...) IDs. All tools read the local snapshot except gradebook_sync, which logs in to ParentVUE and refreshes it.

The dashboard provides the same practical views: student and term selection, course grades and assignments, consolidated missing work, sync status, and a manual sync button.

Configuration

Settings come from environment variables; a local .env file is loaded when present. See .env.example for descriptions and examples.

Listeners and storage

At least one of PORT or UI_PORT must be set.

ParentVUE and sync

Without all three ParentVUE credentials, the service still starts but cannot sync. Manual syncs are always available when credentials are configured.

Before enabling automatic sync, check your district's terms: some districts prohibit automated logins. When enabled, the first sync runs 2–7 minutes after startup and later runs use the configured interval. Only one sync can run at a time.

Authentication and network safety

Authentication protects the MCP endpoint only. When MCP is enabled, configure exactly one mode:

1. Bearer token: set MCP_BEARER_TOKEN to a random value of at least 16 characters. Clients send Authorization: Bearer <token>.

2. Cloudflare Access: set ACCESS_TEAM_DOMAIN, ACCESS_AUD, and at least one identity in ALLOWED_EMAILS or ALLOWED_SERVICE_TOKENS. The server verifies the Access JWT and its allowlist.

The two listeners have different trust boundaries:

• MCP is authenticated. For remote access, place it behind TLS using an identity-aware proxy, a private overlay such as Tailscale or WireGuard, or a TLS reverse proxy such as Caddy or nginx. Never send a bearer token over plain HTTP on a public network.

• The dashboard is not authenticated. Anyone who can reach it can read all stored grades and trigger a ParentVUE login. Restrict it to a trusted private network and never route a public hostname or tunnel to it.

Compose publishes both ports on loopback by default. Change the corresponding *_BIND_ADDR only when the selected interface is private or another layer provides the required protection.

Data behavior

Syncs merge ParentVUE data into gradebook.sqlite. They do not write back to the district. Assignments that disappear upstream are marked stale instead of deleted, and course-grade and assignment-score changes are retained as history. Each student's overview carries a "What's new" summary — new assignments, score changes, and work that newly went missing — that stays in place until a later sync brings something newer.

Every MCP call is audit-logged with the resolved identity, tool, arguments, duration, and outcome. Sync runs also record their trigger and result. The dashboard limits new sync attempts to one per minute to reduce the risk of a ParentVUE account lockout.

Upgrading

docker compose pull
docker compose up -d

GRADEBOOK_VERSION in .env controls what pull fetches: blank follows the latest release, 0.2 takes only fixes to that line, and 0.2.0 stays put. Database migrations run automatically on startup and cannot be undone, so take a backup first. Release notes are on the GitHub Releases page.

Backup and restore

The database uses SQLite WAL mode, so do not back up only the .sqlite file while the service is running. Use the consistent-backup script from scripts/backup.sh:

curl -fsSLO https://raw.githubusercontent.com/songsterq/gradebook-mcp/main/scripts/backup.sh
chmod +x backup.sh
BACKUP_DIR=/path/to/backups KEEP_DAYS=14 ./backup.sh

It creates and verifies a snapshot through the running container and removes successful backups older than KEEP_DAYS. CONTAINER defaults to gradebook-mcp; BACKUP_DIR defaults to ./backups.

To restore, stop the service and replace the database plus its WAL files in the named volume:

docker compose down
docker run --rm --user 1000:1000 \
  -v gradebook_gradebook-data:/data \
  -v "$PWD/backups:/backup:ro" \
  alpine sh -c "rm -f /data/gradebook.sqlite /data/gradebook.sqlite-wal /data/gradebook.sqlite-shm && cp /backup/gradebook-<timestamp>.sqlite /data/gradebook.sqlite"
docker compose up -d

Adjust the volume prefix if your checkout directory or COMPOSE_PROJECT_NAME differs. Do not run docker compose down -v unless you intend to delete all stored data.

Local development

Requires Node.js 22.16 or newer and pnpm 12.3.4.

npx pnpm@12.3.4 install
cp .env.example .env
pnpm dev

For dashboard-only development, set:

PORT=
UI_PORT=3001
UI_HOST=127.0.0.1

For local MCP development without authentication, set:

NODE_ENV=development
HOST=127.0.0.1
DEV_INSECURE_NO_AUTH=true

The bypass works only outside production on a loopback address.

To run the container from your checkout instead of the published image:

docker compose -f compose.yaml -f compose.build.yaml up -d --build

pnpm build
pnpm test

The ParentVUE client is a zero-dependency package in src/lib/parentvue with its own documentation and tests.

Releasing

1. Set version in package.json and merge that to main.

2. Tag the merge and push the tag:

   git tag v0.2.0
   git push origin v0.2.0

The release workflow runs CI, checks the tag against package.json, publishes ghcr.io/songsterq/gradebook-mcp for amd64 and arm64 (tags 0.2.0, 0.2, and latest), and creates a GitHub Release with generated notes.

License

MIT — see LICENSE.