WilmAI

What is WilmAI about?

WilmAI connects the Wilma school information system (used by Finnish schools) with popular AI assistants such as Claude, ChatGPT, Codex, OpenClaw, Grok Bot and Meta Muse. It runs entirely on the user's computer, exposing a set of MCP tools that fetch schedules, homework, exams, grades, messages, news, printouts and more. A companion desktop application, WilmAI Home, presents this data in a modern UI for parents and students.

How to use WilmAI?

1. Install the CLI – npm i -g @wilm-ai/wilma-cli or run it on‑demand with npx -y @wilm-ai/wilma-cli@2 mcp.
2. Log in – execute wilma login; a browser window opens on 127.0.0.1 where you select your school's Wilma and enter credentials. The login is stored locally.
3. Run the MCP server – npx -y @wilm-ai/wilma-cli@2 mcp. Any MCP‑compatible client (Claude Desktop, ChatGPT Desktop, Codex, OpenClaw, etc.) can now call tools like wilma_summary or wilma_schedule.
4. Add skills to your assistant – follow the one‑click guides on wilm.ai for each assistant (e.g., download wilmai.mcpb for Claude Desktop or send a single message to Grok Bot to install the CLI and skill).
5. Use the desktop app – download WilmAI Home for macOS or Windows, sign in with the same Wilma credentials, and start viewing or replying to school information.

Key features of WilmAI

• 19 ready‑made MCP tools covering summary, schedule, homework, exams, grades, lesson notes, messages, news (with attachments), printouts and logout.
• CLI that outputs human‑readable text or JSON for scripting.
• Agent skills (wilma and wilma‑triage) that let assistants answer natural‑language questions or post daily family briefings.
• Local‑only operation – no external WilmAI server, no telemetry; credentials never leave the user’s device.
• Multi‑Wilma support – handle families with children attending different schools.
• Cross‑assistant compatibility – works with Claude Desktop, ChatGPT Desktop, Codex, Grok Bot, Meta Muse, OpenClaw and the terminal.
• WilmAI Home – Tauri‑based desktop app with optional AI (OpenAI or local) for message summarisation, notifications, and write‑back capabilities.

Use cases of WilmAI

• Morning briefings – an AI assistant posts a daily summary of each child’s schedule, homework and upcoming exams to a family chat.
• On‑demand queries – ask “What do the kids have tomorrow?” and receive a concise answer covering all children.
• Automated notifications – configure wilma‑triage to flag urgent messages or exams and add them to a shared calendar.
• Parent monitoring – parents use WilmAI Home to view grades, messages and attendance without opening the official Wilma web portal.
• Student self‑service – a teenager signs in with their own Wilma account in WilmAI Home to check homework and reply to teachers.

FAQ from the WilmAI community

Q: Do I need a WilmAI account? A: No. The tools run locally and only log in to your school's Wilma.

Q: Is my password safe? A: The password is entered on a local browser page and stored obfuscated in ~/.config/wilmai/config.json. It never travels to any third‑party service.

Q: Can I use it on a corporate laptop that intercepts TLS? A: Yes. Set NODE_USE_SYSTEM_CA=1 or use NODE_EXTRA_CA_CERTS to point Node at the corporate root CA as described in the troubleshooting section.

Q: Which assistants are supported? A: Claude Desktop, ChatGPT Desktop (Work mode), Grok Bot, Meta Muse, OpenClaw, Claude Code, Codex, and any generic MCP client.

Q: How do I uninstall? A: Run npm uninstall -g @wilm-ai/wilma-cli (or remove the global package) and delete the config files at ~/.config/wilmai/.

Q: Does WilmAI write data back to Wilma? A: Apart from wilma_logout (which ends the session), all tools are read‑only. The desktop app can send messages or register for events, but only after you explicitly perform the action.

WilmAI

Wilma, Finland's school system, with AI. Two ways to use it, both free and open source:

For your AI assistant or agent An MCP server, a CLI and agent skills. Ask Claude, ChatGPT, Codex, OpenClaw, Grok Bot or Meta Muse about school in plain words, or let your agent post one briefing for the whole family every morning.

Set up your assistant →

WilmAI Home, the desktop app A fast, modern Wilma app for students and parents: lessons, messages, homework, exams and grades in one view, a notification when something needs you, and AI if you want it. Free and open, now in beta, for Mac and Windows.

Download WilmAI Home → · More

wilm.ai (English and Finnish) · Set up · WilmAI Home, the desktop app · Changelog

You: What do the kids have at school tomorrow?

Your assistant: Kiia has crafts 8:30–11:00, then geography and math; her English exam is on Thursday (units 7–9). Eino starts at 9:15 with swimming, so pack a swimsuit and towel. There's also a new message from the class teacher about Friday's trip: the permission form is due Wednesday.

WilmAI connects Wilma, the system Finnish schools use for schedules, homework, exams, grades and messages, to the AI assistant or agent you already use. It's an MCP server, a command-line tool and two agent skills, free and open source. There's also WilmAI Home, a desktop app of its own for students and parents.

Disclaimer: This is an independent open-source project by a parent, not affiliated with, endorsed by, or connected to Visma or the official Wilma service.

What you get

• 19 MCP tools. Summary, schedule, homework, exams, grades and the gradebook, lesson notes and absences, messages with replies, news with attachments, printouts, and a logout. One call covers every child, across every Wilma the family uses.
• A CLI for people and agents. Text in a terminal, JSON when a program reads it: the same JSON as the MCP tools. wilma summary --since yesterday returns only what's new, for daily runs.
• It all runs on your computer. No WilmAI server, no account, no telemetry. It logs in only to your school's Wilma and can't send messages or change anything there. The password goes into a local login page, never into a chat.
• Agent skills. wilma teaches an agent the tools and commands; wilma-triage turns them into a morning briefing that flags what needs doing and puts exams in the family calendar.
• Any school on Wilma. The login page finds your school's Wilma by city or school name. Two-step verification and families with several Wilmas work.

Try it in one line

# Claude Code
claude mcp add --scope user wilma -- npx -y @wilm-ai/wilma-cli@2 mcp

# Codex
codex plugin marketplace add aikarjal/wilmai && codex plugin add wilma@wilmai

# Any MCP client
npx -y @wilm-ai/wilma-cli@2 mcp

# Just the terminal (Node.js 20.18 or newer)
npm i -g @wilm-ai/wilma-cli && wilma login && wilma summary

Then ask about school. The first time, a login page opens in your browser: pick your school's Wilma and log in. The login is saved on your computer.

Add WilmAI to your assistant

Step-by-step guides for parents, in English and Finnish: wilm.ai.

Assistant	How	Guide
Claude Desktop (Mac, Windows)	Download wilmai.mcpb and open it; Claude asks whether to install it	wilm.ai#claude
ChatGPT desktop app (Mac, Windows)	In Work mode (not Chat), send ChatGPT one message and it installs the plugin itself; or add the MCP server npx -y @wilm-ai/wilma-cli@2 mcp yourself	wilm.ai#chatgpt
Grok Bot	Send one message; the bot installs the CLI and skill itself	wilm.ai#grok
Meta Muse (not in Finland yet)	Send one message; Muse installs the CLI and skill itself, and asks you to save your Wilma login in its vault	wilm.ai#muse
OpenClaw	Send one message and OpenClaw installs the CLI and the wilma skill; a second one starts a daily briefing with wilma-triage	wilm.ai#openclaw
Claude Code	claude mcp add --scope user wilma -- npx -y @wilm-ai/wilma-cli@2 mcp	wilm.ai#claude-code
Codex	codex plugin marketplace add aikarjal/wilmai, then codex plugin add wilma@wilmai	wilm.ai#codex
Terminal	npm i -g @wilm-ai/wilma-cli, then wilma login	wilm.ai#cli

Not supported: Claude and ChatGPT on the web and in the phone apps. Your login stays on your own devices and WilmAI runs no server in between; for updates on your phone, use an agent with its own computer, such as OpenClaw or Grok Bot. Not yet available in Finland: Meta Muse (US and Canada so far), Instinct, and OpenAI dots on consumer plans.

What you can ask

In your own words; every question covers all your children.

• "What do my kids have going on at school this week?"
• "Is there any homework for tomorrow?"
• "Are there any exams coming up? What should she study?"
• "Has any teacher left a note about Eino this month?"
• "Any new messages from school? Read the attached letter too."
• "How did the last exams go? What was on the spring report card?"

Or give an agent a routine: "Every weekday at 7, post a school briefing for both kids to the family channel, and put new exams in the family calendar." The wilma-triage skill does exactly that.

What's inside

• packages/wilma-client – TypeScript Wilma client (auth + parsing + tenant list)
• packages/wilma-cli – CLI (wilma), browser login (wilma login), and MCP server (wilma mcp)
• skills/ – Agent skills (wilma, wilma-triage); also the plugin root for Claude Code and Codex
• apps/site – wilm.ai (Next.js, built as static files and served by Cloudflare Workers)
• apps/home – WilmAI Home, the desktop app (Tauri), and its eval suite

Logging in

wilma login

Opens a one-time page on 127.0.0.1 in your browser. Pick your school's Wilma, log in, and the verified login is saved to ~/.config/wilmai/config.json (or $XDG_CONFIG_HOME/wilmai/config.json; override with WILMAI_CONFIG_PATH). The password is entered on that page — never in an agent's chat.

Children on different Wilmas (say, a city school and a private school or lukio)? Press Add another Wilma on the same page, or run wilma login again. Every saved login is used together: every command covers all your children. wilma accounts lists the saved logins and wilma accounts remove <number> removes one.

Wilma allows one session per account: when WilmAI logs in, Wilma logs you out in your browser, and the other way round. WilmAI keeps its session and logs in again only when Wilma has ended it. To use Wilma in the browser, run wilma logout or ask your assistant to log out of Wilma (wilma_logout). That ends WilmAI's session and keeps the login; the next command or question logs in again.

Without a browser (scripts, agents on cloud computers), first find the Wilma address:

wilma find-school <city or school>

then:

WILMA_PASSWORD=... wilma login --tenant <city> --username you@example.com
printf '%s' "$PASSWORD" | wilma login --tenant https://<school>.inschool.fi --username you@example.com --password-stdin

Or skip the saved login entirely by setting environment variables, e.g. in an agent's secret settings:

Variable	Value
WILMA_TENANT	Wilma address (https://<school>.inschool.fi) or city/school name
WILMA_USERNAME	Wilma username
WILMA_PASSWORD	Wilma password
WILMA_TOTP_SECRET	Authenticator setup key, if the account uses two-step verification

Running wilma without arguments in a terminal opens an interactive menu.

MCP server

wilma mcp

A stdio MCP server with these tools: wilma_summary, wilma_schedule, wilma_homework, wilma_upcoming_exams, wilma_grades, wilma_gradebook, wilma_lesson_notes, wilma_lesson_notes_summary, wilma_list_messages, wilma_read_message, wilma_list_news, wilma_read_news, wilma_get_news_attachment, wilma_list_printouts, wilma_get_printout, wilma_account, wilma_find_school, wilma_login, wilma_logout. They only read from Wilma, except that wilma_logout ends WilmAI's Wilma session. Every tool covers all children unless student is given, and the JSON is the same as the CLI's. If nobody is logged in, tools open the browser login and tell the assistant what to relay.

Any MCP client can run it with npx -y @wilm-ai/wilma-cli@2 mcp. For Claude Code: claude mcp add --scope user wilma -- npx -y @wilm-ai/wilma-cli@2 mcp (--scope user makes it available in every project).

Build the Claude Desktop extension locally with pnpm --filter @wilm-ai/wilma-cli build:mcpb (output: packages/wilma-cli/build/wilmai.mcpb). The release workflow attaches it to each GitHub release.

CLI

npm i -g @wilm-ai/wilma-cli

wilma summary                 # daily briefing for every child
wilma schedule tomorrow
wilma exams
wilma notes --days 7          # absences and teachers' feedback
wilma messages 27164611       # one message with its replies
wilma news 73291 download 1   # a file linked from a bulletin
wilma help <command>

Every command covers all children (--student narrows), prints JSON when another program reads it and text in a terminal, and gives times in Finnish time. Commands continue the last Wilma session instead of logging in each time. See the CLI README.

News JSON includes structured resources for every link in a bulletin. Any resource can be downloaded with wilma news <news-id> download <resource-id> --output <directory>. Wilma-hosted files download through the authenticated session; external URLs are fetched with an isolated, unauthenticated request that never carries Wilma credentials. The CLI does not guess whether a URL is a file — it attempts the download and reports downloaded or not_a_file (a web page answered, e.g. a sign-in wall).

Skills

npx skills add aikarjal/wilmai

From source

pnpm install
pnpm --filter @wilm-ai/wilma-client build
pnpm --filter @wilm-ai/wilma-cli build
node packages/wilma-cli/dist/index.js

Working on WilmAI or releasing it: DEVELOPING.md. Tests: TESTING.md.

WilmAI Home, the desktop app

School, sorted. WilmAI Home is a fast, modern Wilma app for students and parents, free and open, now in beta: messages, timetables, homework, exams and grades for every child in one view, a notification when something new needs you, and optional AI that reads each new message and picks out what needs you and by when.

Download for Mac or Windows · What it does · Releases

• Reads and writes. Reply to teachers, write new messages, sign up for parents' evenings and report absences, without opening Wilma. Pin the messages you keep coming back to.
• For a student too. Sign in with a student's own Wilma account and choose "A student": the app then reads things from the student's side.
• AI is optional. No AI (the default), OpenAI with your own API key (usually tens of cents a month; the app stops at a monthly limit you set), or local AI on an Apple Silicon Mac with 16 GB of memory, where nothing goes to an AI service.
• Stays on your computer. No WilmAI server and no tracking. Your Wilma password goes only to your school's Wilma; the app keeps it (scrambled) only if you turn on staying signed in.
• Updates itself. New versions arrive in the app, signed with the project's update key; you choose when to install them.

Mac (Apple Silicon, macOS 13.3 or later) and Windows 10 or 11. The installers aren't signed by Apple or Microsoft yet, so the first start needs one extra step: on a Mac, System Settings → Privacy & Security → Open Anyway (the install window has a link); on Windows, More info → Run anyway. On Windows, notifications and local AI aren't there yet.

The source is in apps/home (Tauri, React and Rust), with its own README for building and the eval suite that measures how well the AI reads school messages.

Troubleshooting

fetch failed on a managed or corporate laptop

If any command fails with a TLS certificate error, your network is very likely intercepting TLS ("break-and-inspect") and re-signing certificates with a private root CA — standard on devices behind a corporate secure web gateway. Node ships its own CA bundle and ignores the operating system trust store, so a root your browser already trusts is invisible to Node.

The CLI reports the underlying cause code (for example UNABLE_TO_GET_ISSUER_CERT_LOCALLY) and the fix. In order of preference:

# 1. Node >=22.19 / >=24.6
NODE_USE_SYSTEM_CA=1 wilma summary

# 2. Node >=22.15 (the flag has wider version support than the env var)
node --use-system-ca "$(command -v wilma)" summary

# 3. Point Node at the proxy root explicitly
NODE_EXTRA_CA_CERTS=/path/to/root-ca.pem wilma summary

Never set NODE_TLS_REJECT_UNAUTHORIZED=0. It disables certificate verification entirely, on a network that is already inspecting your traffic.

Two things that make this hard to recognise:

• A working npm install proves nothing. Inspection policies commonly exempt registry.npmjs.org, so installing the CLI succeeds while every Wilma request fails.
• curl and your browser work fine, because they use the OS trust store. Only Node is affected, which makes the network look healthy.

Credentials & Privacy

Your Wilma login is stored locally in ~/.config/wilmai/config.json (or $XDG_CONFIG_HOME/wilmai/config.json), readable only by your user account. The password is obfuscated (not encrypted) for convenience — this is a personal productivity tool, not a vault. The current Wilma session is kept next to it (wilmai-sessions.json, same protection, at most 6 hours) so commands don't log in each time; set WILMAI_NO_SESSION_CACHE=1 to turn that off. wilma logout ends the session in Wilma and removes it, keeping the login; wilma config clear removes both.

The CLI, the MCP server and the Claude Desktop extension have no server behind them: they log in only to your school's Wilma. Besides Wilma, they open links from school bulletins when you ask for an attachment (only public websites, never with your Wilma login), and once a day they ask npm whether a newer version is out (not when started through npx, which fetches the newest version itself; WILMAI_NO_UPDATE_CHECK=1 turns it off). When an AI assistant uses WilmAI, the school information it reads goes to that assistant's provider, the same as pasting it into a chat; your password does not.

Do not share your config file. It accesses the same data as the official Wilma app or website; it is your responsibility to handle that data appropriately.

License

MIT. Questions, bugs and ideas: GitHub issues. If WilmAI is useful to you, a star helps other parents find it.