vklass-mcp

A multi-user Model Context Protocol server for Vklass guardians, with data access and explicitly confirmed absence reporting. Every user authenticates their own Vklass account with BankID as part of the standard MCP OAuth flow. Each OAuth subject maps directly to one Vklass user ID; there is no shared login, global MCP token or administrator password.

The MCP protocol surface is designed like a first-party remote MCP server. The Vklass integration is necessarily unofficial because Vklass does not publish a guardian API; its web endpoints can change.

MCP and identity model

• One Streamable HTTP endpoint: /mcp.

• OAuth 2.1 authorization code flow with S256 PKCE.

• OAuth Authorization Server Metadata and RFC 9728 Protected Resource Metadata.

• Dynamic Client Registration for compatible MCP clients.

• Rotating access and refresh tokens, revocation, scopes and RFC 8707 resource indicators.

• The OAuth authorization page starts the Göteborg Vklass BankID QR flow.

• After login, Vklass appData.userId is transformed into a stable server-local pseudonymous OAuth subject using the state key; the raw Vklass user ID is not stored in OAuth grants.

• Each subject receives its own Vklass session, SQLite cache, synchronization tasks and encrypted state directory. Data queries can never select another subject's database.

• Raw OAuth access/refresh/code values are SHA-256 hashed in SQLite. Registered client metadata, including client secrets, is encrypted with the server state key.

• When the upstream Vklass session expires, all grants for that Vklass subject are revoked so MCP clients receive a standard 401 and restart the BankID authorization flow.

MCP clients connect only to:

https://vklass.example.com/mcp

A compatible client discovers OAuth, opens the browser, asks the user to approve BankID, and stores its own tokens. Different users and clients use the same URL but receive different OAuth subjects.

The server uses separate least-privilege OAuth scopes: vklass.read for cached and live queries, and optional vklass.write for absence reporting. Existing read-only clients remain read-only; they must re-register and authorize the write scope before they can submit reports.

Related MCP server: librus-mcp

Security

• The only exposed Vklass mutation is guardian absence reporting. Leave, messages, schedule changes, deletion and other mutations are not exposed.

• Absence tools require vklass.write plus confirm=true, use a fresh Vklass anti-forgery token, restrict the child to the authenticated guardian's current wards, and honor school date limits. New clients receive read-only scope by default and must explicitly request write access.

• An interrupted submission returns outcome_unknown; clients must inspect Vklass rather than retrying automatically and risking a duplicate report.

• BankID approval is always performed by the account owner in a browser.

• Vklass cookies and OAuth secrets are never returned through MCP or logs.

• Göteborg SAML and BankID form/redirect hosts are strictly allow-listed.

• Vklass content is treated as untrusted data, never as instructions.

• The container runs without root or capabilities and uses a read-only root filesystem.

• Production OAuth requires a public HTTPS origin. The container port binds to loopback for a TLS reverse proxy and must not be published directly.

If this service is offered to other parents, the operator becomes responsible for personal data. Provide clear retention/deletion terms, protected backups, incident handling and an operator contact. Users should also understand that their MCP client may send tool results to its model provider.

Implemented Vklass coverage

MCP tools

• vklass_capabilities, vklass_status, vklass_sync_now

• vklass_list_children

• vklass_report_absence_today, vklass_report_absence_period (vklass.write)

• vklass_list_weekly_letters, vklass_get_weekly_letter

• vklass_list_news, vklass_get_news_article

• vklass_list_calendar, vklass_list_assignments, vklass_list_care_schedule

• vklass_list_automatic_weekly_reports

• vklass_get_meals, vklass_get_notifications

• vklass_list_study_courses, vklass_get_feature_snapshot, vklass_search

Local development

Requires Python 3.12+ and uv.

cp .env.example .env
# For localhost only:
sed -i 's#https://vklass.example.com#http://127.0.0.1:8000#' .env
sed -i 's#VKLASS_STATE_KEY_FILE=.*#VKLASS_STATE_KEY=development-state-key-change-me#' .env
uv sync --all-groups
uv run pytest
uv run vklass-mcp

Connect a development MCP client to http://127.0.0.1:8000/mcp. Do not use HTTP on a LAN or the internet.

Podman and systemd

make build
make install-quadlet
$EDITOR ~/.config/vklass-mcp/server.env
systemctl --user start vklass-mcp.service
journalctl --user -u vklass-mcp.service -f

The installer creates only one Podman secret: vklass-mcp-state-key. OAuth clients and users create their own credentials through the protocol. Version 0.2 deliberately refuses to start when legacy single-user vklass.db* or session.json.fernet files remain at the data root; migrate them or securely remove the complete legacy set before deployment.

Runtime locations:

~/.config/vklass-mcp/server.env
~/.local/share/vklass-mcp/oauth.db
~/.local/share/vklass-mcp/users/<sha256-of-vklass-user-id>/
~/.config/containers/systemd/vklass-mcp.container

The Quadlet binds 127.0.0.1:8787. Put Caddy or another TLS reverse proxy in front of it:

vklass.example.com {
    reverse_proxy 127.0.0.1:8787
}

Set both VKLASS_PUBLIC_BASE_URL=https://vklass.example.com and VKLASS_ALLOWED_HOSTS=vklass.example.com,localhost:*,127.0.0.1:*. The public URL is the OAuth issuer and cannot be changed without requiring clients to authorize again.

For the user service to survive logout:

loginctl enable-linger "$USER"

Production deployment on perd25

deploy/perd25/ builds locally, transfers the image through SSH to the dedicated perapp account, installs a hardened Quadlet in that account's rootless Podman store, and attaches it only to the private perapp network without publishing a host port. The independent perapp-edge Caddy service owns public TLS and routes https://vklass.perapp.dev to the container alias.

make build
./deploy/perd25/deploy.sh

Set VKLASS_DEPLOY_ACTIVATE=0 to transfer the image and install the Quadlet without starting the service during a coordinated migration. The public OAuth issuer is independent of the service account and internal port.

Back up ~/.local/share/vklass-mcp/ together with ~/.config/vklass-mcp/state-key; losing the key disconnects every user and makes encrypted sessions and OAuth client registrations unreadable.

Operations

• Health: GET /healthz

• OAuth metadata: GET /.well-known/oauth-authorization-server

• Protected resource metadata: GET /.well-known/oauth-protected-resource/mcp

• OAuth revocation: POST /revoke

• SQLite and encrypted sessions must be backed up together with the state key.

• OAuth grants can be revoked through /revoke; local data deletion is currently an operator-assisted action so an MCP read token cannot trigger destructive account management.

• BankID authorization transactions are intentionally process-local; run one application worker.

• Built-in per-peer rate limits, global authorization limits, concurrent BankID slots and a resident service cap provide backstops. Apply stricter distributed limits at the TLS edge for public use.

• Keep the state key stable and backed up. Rotation requires a planned migration of encrypted client metadata, user sessions and pseudonymous OAuth subjects; replacing it directly disconnects users.

Attribution

The Göteborg BankID flow is adapted from the MIT-licensed Kaptensanders/vklass. See THIRD_PARTY_NOTICES.md.