schoolsoft-agent

SchoolSoft for AI agents. Lets an agent (Claude, OpenCode, OpenClaw, Hermes, Pi, …) read a guardian's SchoolSoft data: schedule, full calendar, lunch menu, assignments, news and the message inbox. Login is BankID in your own browser; nothing is automated around it, and the session is stored encrypted on the computer or server you operate.

Choose the connection your assistant supports:

The local MCP server and CLI expose the same operation registry. The remote connector exposes a restricted selection with separate login and child permissions. All share the same core. See docs/development/architecture.md.

Independent project. SchoolSoft is a trademark of SchoolSoft AB. This is an independent, MIT-licensed community project: it is not affiliated with, endorsed by, or supported by SchoolSoft AB, and SchoolSoft has no involvement in it. It talks to SchoolSoft through the same unofficial APIs the SchoolSoft app uses; read Trademark and independence and Privacy before installing.

Start here

Browse all documentation.

New to AI assistants? Start with the parent setup guide. It helps you choose one app, install SchoolSoft, complete BankID and check your first answer.

• Mac or Windows, graphical setup: Claude Desktop in five steps.

• Already chose an assistant: find its guide, including ChatGPT/Codex, OpenClaw, Hermes, Pi and OpenCode.

• Want Claude/ChatGPT without a local agent: parent-hosted connector setup. The implementation and deployment recipes are a release candidate; real SchoolSoft login and AI client/mobile acceptance are still pending. Do not buy hosting expecting a proven phone setup yet.

The detailed support matrix compares desktop, web, mobile and remote-computer setups, including effort and current limitations. You do not need to read it to follow the recommended desktop guide.

Related MCP server: fskintra-mcp

Try it in a terminal first (optional)

Prerequisite: Node.js 22 or newer.

npx -y schoolsoft-agent                                    # a guided first run, in Swedish or English

It asks for your school's name, opens BankID in your own browser, checks that SchoolSoft answers, shows this week's schedule and says where your data is kept and how to add an AI assistant. Stop with Ctrl+C at any time; npx -y schoolsoft-agent setup continues where you left off. The same steps one by one, for scripts (setup --query "<name>" does them without asking):

npx -y schoolsoft-agent configure --query "Rösjöskolan"   # finds your school
npx -y schoolsoft-agent login                              # BankID in your browser
npx -y schoolsoft-agent get-calendar --pretty              # lessons and school events this week (JSON)
npx -y schoolsoft-agent get-schedule --format text         # this week's schedule, laid out for people

Output is JSON for assistants and scripts; --format text shows children, schedule, calendar, lunch and messages as views for people.

Every command is in the command reference; every crucial one is also a make target in a checkout (make help). Messages come in Swedish when your system language is Swedish (or with SCHOOLSOFT_LANG=sv), always as "what went wrong" plus "Next: what to do".

What you can ask

• "Vad har Ella på schemat på fredag?"

• "Vad är det till lunch i veckan?"

• "What is happening at school next week, including lessons and school events?"

• "Har vi fått några meddelanden från skolan?"

• "Vilka läxor finns den här veckan?"

The agent picks the child (list_children), the week, and the right operation. Contact lists, bookings and shared files have no data feed at SchoolSoft; those are read through an optional hidden browser (npx -y schoolsoft-agent browser install, once). Grades, student documents, absence reports and assessment criteria additionally sit behind SchoolSoft's "log in again" gate and need npx -y schoolsoft-agent login --web once, a normal web login in a browser window. Both extras are explained step by step in Get started. Full list of what an agent can ask for: MCP tools · CLI commands.

The parent-hosted connector currently supports children, schedule, calendar and lunch only. Messages, assignments and the extra browser features above belong to the local MCP/CLI routes.

How login works

For the local MCP server and CLI:

1. The agent calls login. Your browser opens SchoolSoft's real login page for guardians.

2. You authenticate with BankID (or whatever your municipality offers). Enter your login details only on the official login page, never in the assistant.

3. SchoolSoft redirects to http://127.0.0.1:43117/callback with a one-time code; the integration exchanges it for tokens and session cookies.

4. Tokens are stored encrypted (AES-256-GCM, key file 0600) and refreshed silently. You log in again only when the refresh token expires.

For the parent-hosted connector, start login on your server's owner page. The browser returns to that server's HTTPS callback; its acceptance by SchoolSoft needs a real test. The session stays on your server, and each AI app gets separately revocable permission for selected children. Follow the connector guide.

Login problems are covered in Troubleshooting. Details and diagrams: docs/development/architecture.md. What SchoolSoft actually exposes: docs/reference/schoolsoft-api.md.

Privacy

How your family's data is handled explains, in plain language, what is stored, where, for how long, and what reaches your AI provider, SchoolSoft and your hosting provider. In short:

• Requested school information is sent to your chosen assistant/model provider, which handles it under its own terms. A messaging interface may involve another provider. This project has no telemetry, crash reporting or analytics, and no author-operated service receiving family data.

• Local installations save an encrypted session under your platform's config directory (schoolsoft-agent doctor shows where). schoolsoft-agent logout deletes that session. The parent-hosted connector also saves encrypted permissions and owner identity on your server; follow its deletion steps.

• With parent hosting, your hosting provider and anyone administering your server may access data while it is processed. Encryption at rest does not prevent that access. The project author does not host your copy or receive its SchoolSoft session.

• Nothing is written to log files. The few diagnostic lines on stderr contain no children's names or school content.

• This is unofficial automated access. Check SchoolSoft's terms of service for your municipality before relying on it.

• Reporting an absence is the only tool that changes anything at SchoolSoft. It is off unless you set SCHOOLSOFT_ALLOW_WRITES=1 and previews before sending. Every other tool only reads, and the hidden browser blocks any request that could change something.

Development

git clone https://github.com/grimen/schoolsoft-agent && cd schoolsoft-agent
make setup          # node check + npm ci + git hooks
make check          # lint, typecheck, format, boundaries, manifests, tests with coverage
make e2e-artifact   # shipped-artifact + host E2E in a sandbox (what CI runs)
make e2e            # live suite against SchoolSoft (needs configure + one login)
make help           # everything else

Layout, boundaries, design principles and the test pyramid are in docs/development/architecture.md; conventions, hooks and the CI stages in CONTRIBUTING.md; how versions ship in docs/development/releasing.md; the rules every coding agent follows in AGENTS.md. What we know about SchoolSoft's unofficial APIs and web pages, page by page, is in docs/reference/schoolsoft-api.md. Adding an operation touches one file under src/core/operations/ plus the registry; both surfaces and the docs follow.

Roadmap

• Write operations: report absence, send message (separate spec; confirmation-gated).

• Parent-hosted connector acceptance: the HTTP implementation and deployment recipes are present. Complete real SchoolSoft public-callback login, both AI clients, mobile availability and recovery checks before calling it supported. Setup and remaining checks.

• Claude Desktop extension directory listing.

• Other school portals: everything vendor-specific sits behind one SchoolProvider seam (src/providers/), so a second Swedish portal is a new provider directory, not a rewrite. All of them end their login in BankID, which the core already handles two ways.

Trademark and independence

SchoolSoft is a trademark of SchoolSoft AB. This is an independent, MIT-licensed community project: it is not affiliated with, endorsed by, or supported by SchoolSoft AB, and SchoolSoft has no involvement in it. The name is used only to describe what the software connects to. BankID is a trademark of Finansiell ID-Teknik BID AB; Claude, ChatGPT, OpenCode, OpenClaw, Hermes and Pi are trademarks of their respective owners. All are named descriptively, and none of these organisations is involved in or endorses this project. No logos or brand assets are used. If any rights holder objects to a use of their name, open an issue and it will be addressed.

License

MIT © Jonas Grimfelt. No SchoolSoft client library is bundled: the HTTP code is this project's own. Thanks to the community clients whose published observations helped map the unofficial API, among them elias4044/ssp-node (MIT), a runtime dependency until E6.3, and sebdanielsson/better-schoolsoft. The API knowledge and its sources are documented in docs/reference/schoolsoft-api.md.