somtoday-mcp
A read-only MCP server for the Somtoday parent portal, running locally over stdio.
Identify the account, school, linked children, visible sections, and leerling IDs (
whoami,children,school_info,teachers).View timetable and schedule data, including lessons, tests, exams, rooms, teachers, changes, cancellations, attachments, and holidays (
lessons,schedule).View homework/study-planner items, hand-in assignments, assignment details, and study material (
homework,assignments,assignment_detail,study_material).View grades via summary, latest results, full year overview, per-subject details, and school-exam/PTA/SE dossier (
grades,grades_latest,grades_overview,subject_grades,exam_grades).View absence/registrations and active measures (
absence).Read messages, school news, and Somtoday-wide announcements without marking anything read (
messages,news,announcements).View signing requests and read available signing-request PDFs; view parent-evening details; view consents (
signing_requests,signing_document,parent_evening,consents).Read supported attachments via
download_attachmentand check login/session status viaauth_status.It only performs GET requests, never changes data, never returns tokens, and sends nothing beyond Somtoday.
somtoday-mcp
Read-only MCP server for the Somtoday parent portal. It lets an AI assistant such as Cursor or Claude Desktop look up your child's timetable, homework, and grades from your own parent account.
It runs locally on your computer over stdio. Nothing is sent anywhere except to Somtoday itself.
Disclaimer. This is an unofficial community project. It is not affiliated with, endorsed by, or supported by Somtoday or Topicus. It works by interoperating with the undocumented internal web API that the official parent portal uses, so it may stop working or behave differently at any time without notice. It is intended for use with your own account, only reads data, and is provided as-is, without warranty of any kind (see LICENSE); use it at your own risk and in line with Somtoday's terms of use. "Somtoday" and "Topicus" are trademarks of their respective owners and are used here only to describe what the software works with.
What it does
Tool | What you get |
| Your school label, the linked children with their numeric ids, and which portal sections are visible to you. |
| The timetable for one day, and whether that day is a school holiday. Each lesson has |
| What to do and learn on which day: every study-planner item for a date range (default today + 6 days, max 42), grouped by day, with description, learning goals, time estimate, test type, attachments (links), external links, hand-in window/status and the done tick. |
| The most recent results (up to 30) and averages per subject. |
| All hand-in assignments with window, status (upcoming, to do, waiting for review, approved), late flag, description, attachments and links. |
| One assignment as the parent portal shows it: instruction, files, links, hand-in window and status. Submitted files and teacher reactions are only visible in the student's own session. |
| Study material per subject: lesson material from the planner by date, year attachments by folder (file links), external links, and methods/publisher links. No arguments lists the subjects; |
| Timetable for a date range (default today + 6 days, max 42): time, lesson hour, subject, room, teachers, type (test, exam, parent evening …), lesson notes, changes and cancellations, attachments, holidays. |
| Newest results first with subject, column, description, grade, weight, test type, period, date, remarks and resits; |
| Full grade overview for a school year: every subject, every result per period, report grades, weights and remarks. |
| Everything for one subject: every result column with weights and remarks, column definitions (also not yet graded), composite-test parts, for the progress and exam dossier. No |
| School-exam dossier (PTA/SE): per subject the SE average, every SE result, tests still to come and test-type averages. |
| Absence and registrations for the school year or grading period (absent, late, removed, homework/materials not in order) with counts and entries, plus active measures. |
| Messages, read-only: newest conversations (subject, sender, date, unread, preview; |
| School news items (newest first, as text) and the unread count. |
| Somtoday-wide announcements shown in the portal. |
| Linked children with profile, class, school data (mentors, year, programme), current placement and visible portal sections. |
| School contact data and the school's information pages; |
| Staff you can message, with the subjects they teach your child. |
| Digital signing requests (read-only; nothing is signed). Each item has |
| The (signed) PDF of one signing request, as the portal's download button: pass |
| Parent-evening details (slots, teachers); finds invitations in your messages (read-only; nothing is booked). |
| Consents such as use of photos, as set in the portal (read-only). |
| Read an attachment by |
| Whether a session is stored, where, and how the last token renewal went. Never returns tokens. |
lessonstakes an optionaldate(YYYY-MM-DD, Europe/Amsterdam) and defaults to tomorrow. Range tools takedate, orfrom/to.If more than one child is linked to your account, pass
leerlingId(the numeric id fromwhoami).assignmentswithstatus=openhides past-due items that expect no digital hand-in (inleveringenVerwacht: 0, e.g. handed in on paper) and reports the count inverborgenZonderInlevering; passincludeNoHandIn=trueto see them.assignmentsmerges near-duplicates (same subject, topic, hand-in window and status, e.g. one assignment published to two groups) into one item with the other ids induplicaatToekenningIds; passdedupe=falseto list them separately.If a section is switched off for your account, the tool says so and does not call that part of the API.
Not included: anything that changes data, such as sending messages, reporting absence, booking parent-evening slots, signing requests, or uploading hand-ins.
Related MCP server: pronote-mcp
Read-only and privacy
Tools only send
GETrequests. Nothing is written, submitted, or marked as read.The server talks only to Somtoday's login and API servers.
No telemetry or analytics.
Your password is typed only into the Somtoday login page in a browser window. No tool, CLI flag, environment variable, or prompt ever asks for it.
Tools never return tokens.
Timetables, homework, and grades are personal data about children. Keep the output on your own devices, use only accounts you are entitled to use, and do not share or republish it. Under the GDPR you are responsible for what you do with data you export.
Install
Requires Node.js 24 or newer (the PDF text extraction used by download_attachment and signing_document depends on unpdf 2, which requires Node 24).
Published on npm as somtoday-mcp, with provenance from this repository's release workflow.
npx -y somtoday-mcp # start the MCP server (used by your MCP client)
npx -y somtoday-mcp login # sign in, once, in a terminalLogin opens a normal browser window. When Google Chrome (or else Microsoft Edge) is installed, that browser is used, with a fresh temporary profile that is deleted afterwards; it passes Somtoday's Cloudflare "Verify you are human" check more reliably. Only without Chrome/Edge does it fall back to Playwright's bundled Chromium; install that once in that case:
npx playwright install chromiumThe window is started without the "controlled by automated software" markers; nothing else about the browser is changed.
From a checkout:
git clone https://github.com/barzoj/somtoday-mcp.git
cd somtoday-mcp
npm install
npm run build
npx playwright install chromium # only needed without Chrome/Edge
node dist/cli.js loginMCP client config
Cursor
~/.cursor/mcp.json:
{
"mcpServers": {
"somtoday": {
"command": "npx",
"args": ["-y", "somtoday-mcp"]
}
}
}Claude Desktop
claude_desktop_config.json:
{
"mcpServers": {
"somtoday": {
"command": "npx",
"args": ["-y", "somtoday-mcp"]
}
}
}From a local checkout
{
"mcpServers": {
"somtoday": {
"command": "node",
"args": ["/absolute/path/to/somtoday-mcp/dist/cli.js"]
}
}
}Signing in
Run login in a terminal, not from inside your MCP client:
npx -y somtoday-mcp loginA browser window (your installed Chrome or Edge, else Playwright Chromium) opens on the regular Somtoday login page. Search for your school there, the same way as in the official app.
Sign in as you normally would, including any two-step verification. You have 10 minutes (the Cloudflare check and school search count too).
When the window closes, the session is saved on your computer and the MCP server can use it.
If you know your school's tenant UUID you can skip the school search with npx -y somtoday-mcp login --school-uuid <uuid>.
If a tool is called before you have signed in, or after the saved session stops working, it returns:
run npx somtoday-mcp login in a terminal
Run login again in that case. If Somtoday cannot be reached, tools say so instead of asking you to log in.
Commands
npx -y somtoday-mcp status # where the session is stored, last renewal result (no tokens)
npx -y somtoday-mcp status --check # also renews the token and calls the API once
npx -y somtoday-mcp logout # delete the stored session from this computerThe same diagnostics are available to your MCP client through the auth_status tool.
Several MCP clients (for example two Cursor windows) can share one session: token renewal is serialized with a lock file in the config directory, and each renewal re-reads the stored session first.
OAuth 2.0 authorization code flow with PKCE (S256), using the public (secret-less) client id and redirect URI of Somtoday's native app. There is no client secret and nothing uses the Somtoday Connect partner API.
The login page redirects to a custom
somtoday://URL; Playwright reads the authorization code from that request inside the browser window. No local web server is started.Short-lived access tokens are kept in memory only.
The school is chosen on Somtoday's own login page. The school's tenant comes from the token response (
somtoday_tenant), and the label shown bywhoamiandstatusfrom theorgnameclaim (or, failing that, the school data of your account).
Where the session is stored
Platform | Location |
macOS | Login Keychain, service |
Linux / Windows |
|
To sign out, run npx -y somtoday-mcp logout.
Environment variables
Variable | Effect |
| Base directory for the file fallback (default |
| Use this directory instead of |
| Set to |
Logs go to stderr (stdout is reserved for the MCP protocol) and redact token-like values.
Development
npm install
npm run lint
npm run format:check
npm run typecheck
npm run build
npm testTests never touch the network: fetch and the keychain are mocked, and requests to Somtoday hosts fail on purpose. See CONTRIBUTING.md for the rules on test data and privacy, and SECURITY.md for reporting vulnerabilities.
ouder-portal.openapi.yaml describes the parts of the parent-portal API this project relies on, as observed from the portal; it is not an official specification.
Manual check against a real account
Not part of CI. Write down HTTP status codes only; never paste tokens, codes, names, or API responses.
node dist/cli.js loginand complete the sign-in.Call
whoami,lessons,homework, andgradesfrom your MCP client.Restart the MCP server and call a tool again, to check that the saved session is picked up.
License
MIT. Not affiliated with Somtoday or Topicus.
Available Tools
25 toolsabsenceAbsence and registrationsARead-onlyIdempotent
Registrations for the school year (or current grading period): unexcused and excused absence, late, removed from class, homework not done, materials missing — counts and every entry with date, lesson and remark — plus active measures (e.g. detention).
Inputs: periode, leerlingId.
announcementsAnnouncementsARead-onlyIdempotent
Somtoday-wide announcements (landelijke mededelingen) from the platform itself, such as maintenance notices, with their publication window. Not school news (use news) or personal messages (use messages).
Inputs: no named parameters.
assignment_detailAssignment detailARead-onlyIdempotent
One hand-in assignment as the parent portal shows it: instruction text, learning goals, files (fileUrl) and links, hand-in window, status, late flag and group. Submitted files and teacher reactions are only visible to the student in Somtoday, so they are not returned.
Inputs: toekenningId (required), leerlingId.
assignmentsAssignments (hand-ins)ARead-onlyIdempotent
All hand-in assignments with their window, status (AANKOMEND, IN_TE_LEVEREN, IN_AFWACHTING, AKKOORD), teLaat (always a boolean: true only for an open hand-in past its deadline), description, attachments and links. status=open keeps upcoming and to-do ones, and by default hides past-due items where no digital hand-in is expected (inleveringenVerwacht 0, e.g. on paper; count in verborgenZonderInlevering); includeNoHandIn=true keeps them. Near-duplicates (same subject, topic, window and status, e.g. published to two groups) are merged by default, with the other ids in duplicaatToekenningIds; dedupe=false lists them separately. Use toekenningId with assignment_detail. Every item lists bijlagen (fileUrl, readable with download_attachment) and externeMaterialen; empty means the teacher attached nothing (lesmateriaal=true is only a flag, there is no separate material call).
Inputs: dedupe, status, leerlingId, includeNoHandIn.
auth_statusAuth statusBRead-onlyIdempotent
Whether a Somtoday session is stored, where (keychain or file), and the outcome of the last token renewal. Never returns tokens. Set check=true to renew the token and call the API once.
Inputs: check.
childrenChildrenARead-onlyIdempotent
Linked children with profile (name, student number, class), school data (school, location, mentor(s), year, programme), current placement, and which portal sections the school shows. Use whoami when you only need leerling ids.
Inputs: no named parameters.
consentsConsentsARead-onlyIdempotent
Consents (toestemmingen) as set in the portal: each consent item (e.g. use of photos) with the answer recorded in the portal. Read-only; answers cannot be changed here.
Inputs: no named parameters.
download_attachmentDownload attachmentARead-onlyIdempotent
Read an attachment (fileUrl from homework, assignments, study material or messages). Only https Somtoday file hosts; max 10 MB; returns extracted text for PDF/text/HTML/CSV/JSON, metadata otherwise.
Inputs: url (required).
exam_gradesExam dossier (SE)ARead-onlyIdempotent
School-exam dossier (PTA/SE) overview: per subject the SE average, every SE result, tests still to come, and test-type averages. Says so when the child has no exam dossier yet. Use this for exam-year progress and upcoming SE tests; use grades_latest with dossier=examen for only the newest SE results.
Inputs: examenjaar, leerlingId.
gradesGradesARead-onlyIdempotent
Quick grade summary: the newest progress-dossier results (capped at 30) plus the average per subject. Use grades_latest for more or exam (SE) results, grades_overview for a whole school year, subject_grades for one subject in depth, and exam_grades for the PTA/SE dossier.
Inputs: leerlingId.
grades_latestLatest gradesARead-onlyIdempotent
Newest results first, with subject, column, description, grade, weight, test type, period, date, remarks and resit info. limit defaults to 50 (max 1000, paged). dossier=examen gives school-exam (SE) results. Also the next publication moment when the school uses one. Use this for "what grades came in recently"; use grades for a short summary with averages, subject_grades for all columns of one subject.
Inputs: limit, dossier, leerlingId.
grades_overviewGrade overviewARead-onlyIdempotent
The full grade overview (cijferoverzicht) for a school year: every subject with every result per period, report grades, weights and remarks. Defaults to the current placement; schooljaar like 2025/2026 picks another year. Use this for a whole-year report view or earlier years; use subject_grades for one subject, grades_latest for recent results.
Inputs: leerlingId, schooljaar.
homeworkHomework / study plannerARead-onlyIdempotent
What to do and learn on which day: every studiewijzer item (lesson, day and week items) for a date range, grouped by day, with description, learning goals, time estimate, test type, teacher note, attachments (file links), external links, hand-in window and status, and the done tick. Also lists hand-in deadlines per day. Defaults to today plus 6 days; at most 42 days. Every item lists bijlagen (fileUrl, readable with download_attachment) and externeMaterialen; empty means the teacher attached nothing (lesmateriaal=true is only a flag, there is no separate material call).
Inputs: to, date, from, leerlingId.
lessonsLessonsARead-onlyIdempotent
Timetable for one Amsterdam date, plus whether that date is a holiday. Each lesson has type (ROOSTERTOETS or EXAMEN marks a test in the timetable) and uitgevallen=true when cancelled. Homework and the test topic per lesson are not here: call homework for the same date.
Inputs: date, leerlingId.
messagesMessagesARead-onlyIdempotent
Somtoday messages (berichten), read-only: newest conversations with subject, sender, date, unread flag and a preview; filter with zoek or ongelezen. Pass conversatieId for the full thread (text, sender, recipients, attachments). Never marks anything as read. Use this for personal messages from teachers and the school; school-wide news is in news, Somtoday-wide notices in announcements.
Inputs: zoek, limit, ongelezen, conversatieId.
newsSchool newsARead-onlyIdempotent
News items the school publishes to all parents (nieuwsberichten), newest first, as text, plus the unread count. Use messages for personal conversations and announcements for Somtoday-wide notices from the platform itself.
Inputs: limit.
parent_eveningParent eveningARead-onlyIdempotent
Parent-evening (ouderavond) details: invitation, time slots and chosen teachers. Without id, finds invitations linked in your messages. Read-only; nothing is booked.
Inputs: id.
scheduleScheduleARead-onlyIdempotent
Timetable for a date range, per day: lessons, tests and other appointments with time, lesson hour, subject, room, teachers, type (e.g. ROOSTERTOETS, EXAMEN, OUDERAVOND), lesson notes, changes and cancellations (wijziging, uitgevallen=true, meldingen with real warnings only; the routine 'Inschrijving in orde.' notice is dropped), attachments, and holidays. Every day has items (empty array on a free day). Defaults to today plus 6 days; at most 42 days.
Inputs: to, date, from, leerlingId.
school_infoSchool informationARead-onlyIdempotent
School contact data per child and the school's published information pages. Pass paginaId for one page with its topics and documents. Use teachers for staff and children for mentors.
Inputs: paginaId.
signing_documentSigning documentARead-onlyIdempotent
Read the document (PDF) of one signing request, as the portal's download button does: pass document.id from signing_requests. Returns extracted text (max 10 MB). The document needs your login, so it is not a fileUrl for download_attachment. Usually available once signed; not for requests still to sign, withdrawn or expired.
Inputs: id (required).
signing_requestsSigning requestsARead-onlyIdempotent
Digital signing requests (ondertekenverzoeken) waiting for you or done. Each item has document {tool:'signing_document', id, available}: pass id to signing_document to read the (signed) PDF. Read-only; nothing is signed.
Inputs: no named parameters.
study_materialStudy materialARead-onlyIdempotent
Studiemateriaal per subject: lesson material from the study planner (by date), year attachments by folder (file links), external links, and methods/publisher links (book fund). Without arguments: the subjects that have material, plus personal learning products when the school allows it. vak = name, abbreviation or uuid; all=true fetches every subject. Every item lists bijlagen (fileUrl, readable with download_attachment) and externeMaterialen; empty means the teacher attached nothing (lesmateriaal=true is only a flag, there is no separate material call).
Inputs: all, vak, leerlingId.
subject_gradesSubject gradesARead-onlyIdempotent
Everything for one subject: every result column (tests, assignments, period and report averages, SE averages) with weights and remarks, column definitions (also not-yet-graded ones), and the parts of composite tests. Both progress and exam dossier unless dossier is set. Without vak: the list of subjects. Use this to drill into one subject; use grades_overview for all subjects at once.
Inputs: vak, dossier, leerlingId.
teachersTeachersARead-onlyIdempotent
Teachers and other staff you can message in Somtoday, with the subjects they teach your child. Use children for the mentor(s) and school_info for general school contact data.
Inputs: no named parameters.
whoamiWho am IARead-onlyIdempotent
Start here: the school label, the numeric leerling ids to pass as leerlingId to other tools, and which parent-portal sections are visible. Use children for full profiles. No tokens.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 25 tools
Most tools map to clearly distinct portal resources or actions. The main overlap is the five grade tools and lessons vs schedule, but their descriptions explicitly route between them; whoami vs children also has mild overlap but is clarified.
Almost all tool names are snake_case resource names with no camelCase mixing. whoami is the lone single-token deviation, and parent_evening uses noun_noun rather than an action pattern, but overall naming is predictable.
25 tools is heavy for a parent portal, especially with five grade-related tools and multiple schedule/homework/assignment tools. Each has a distinct role, but the surface is at the upper bound of comfortable scoping.
The tool set covers identity and children, school/staff info, timetable, homework, assignments, study material, all grade views, absence, messages/news/announcements, consents, parent evening, signing documents, attachments, and auth. No obvious domain gap is apparent for a read-only parent portal.
Maintenance
Related MCP Connectors
Read-only MCP server for ClassQuill, a tutoring-business-management platform.
The official Planning Center MCP server for interacting with your ministry's data.
Official Todoist MCP server. Manage tasks and projects. Hosted, no API key needed.
MCP server providing attendance data queries via the CloudTime API.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceAn MCP server for the Bakaláři v3 API that provides access to the popular Czech school management system. It enables users to retrieve schedules, permanent timetables, absence records, and grades through a standardized interface.3MIT
- -licenseNot gradedqualityNot gradedmaintenanceA local MCP server that exposes Pronote (French school management system) data via MCP, enabling AI assistants to retrieve schedules, homework, grades, absences, and more. Supports token-based authentication with QR code setup.-
- AlicenseAqualityDmaintenanceAn MCP server for accessing Dutch school schedules from Magister. Enables Claude and other MCP-compatible AI assistants to query school schedules, drop-off times, and pick-up times.412 npm6MIT
- AlicenseNot gradedqualityDmaintenanceA local MCP server that enables LLMs like Claude to access Schulmanager Online data including schedules, homework, exams, grades, and parental letters.1-