webuntis-mcp
This server gives AI assistants read-only access to a child's WebUntis school data, including timetables, homework, exams, absences, messages, and school info.
Fetch student timetable for any date range (default current week)
Get today's or tomorrow's schedule (tomorrow skips weekends)
Fetch timetable for any class, after listing available classes
List all classes at the school
Get pending homework with due dates
Get upcoming exams and tests
Get registered absences with reasons, status, and notes
Detect timetable changes (cancellations, substitutions, room/teacher swaps)
Get school messages and announcements for a specific date
Get school metadata: period times, holidays, last data import
All tools are read-only; uses TOTP auth; no cloud, no telemetry
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@webuntis-mcp What's on my child's school schedule tomorrow?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
🏫 webuntis-mcp
MCP server for the WebUntis school platform. Timetables, homework, exams, and absences for parents.
💡 What Is This?
An MCP (Model Context Protocol) server that gives AI assistants read-only access to your child's school data on WebUntis. Works with any school that uses WebUntis, anywhere in Europe.
Ask your AI assistant things like:
"What's on the schedule tomorrow?"
"Are there any cancellations this week?"
"Does my child have homework due?"
"When is the next school holiday?"
All data stays on your machine. No cloud service, no telemetry, no account needed beyond your existing WebUntis parent login.
Related MCP server: webuntis-mcp
🚀 Quick Start
1️⃣ Install
# With uv (recommended)
uv tool install git+https://github.com/toughIQ/webuntis-mcp.git
# With pip
pip install git+https://github.com/toughIQ/webuntis-mcp.gitGuided Setup (recommended)
Run the setup wizard to find your school, test your credentials, and generate the config:
# Interactive (walks you through each step)
webuntis-mcp setup
# Non-interactive (for scripts and AI agents)
webuntis-mcp setup --school "My School" --username "parent@example.com" --secret "ABCDEF1234567890" --jsonThe setup command searches the public WebUntis school directory, tests your login, resolves your child's name and class, and saves the credentials to ~/.config/webuntis-mcp/config.env (chmod 600).
2️⃣ Get Your QR Code Secret
You'll need this during setup. To find it:
Log in to WebUntis in your browser (e.g.
yourschool.webuntis.com)Go to Profile (bottom left)
Click the "Freigaben" tab (or "Shares" in English)
Click "Zugriff über Untis Mobile" (or "Access via Untis Mobile")
Copy the Schlüssel / Key value (a 16-character code like
ABCDEF1234567890)
3️⃣ Add to Your AI Client
After running webuntis-mcp setup, your credentials are stored in the config file. The MCP entry only needs the command, no env vars:
Claude Code / Claude CLI:
claude mcp add webuntis-mcp webuntis-mcpCursor / Windsurf / Other MCP Clients:
Add to your MCP settings:
{"mcpServers": {"webuntis-mcp": {"command": "webuntis-mcp"}}}See AGENTS.md for detailed instructions per client.
If you prefer not to use the setup wizard, pass credentials as env vars:
{
"mcpServers": {
"webuntis-mcp": {
"command": "webuntis-mcp",
"env": {
"WEBUNTIS_SERVER": "yourschool.webuntis.com",
"WEBUNTIS_SCHOOL": "yourschool",
"WEBUNTIS_USERNAME": "parent@example.com",
"WEBUNTIS_SECRET": "ABCDEF1234567890",
"WEBUNTIS_STUDENT": "kid1"
}
}
}
}You can find all values in the WebUntis QR code dialog (Profile > Freigaben > Untis Mobile).
4️⃣ Verify
Ask your AI assistant: "What's on the school schedule today?"
If it returns a timetable, you're set.
🛠️ Tools
Tool | Description |
| Student timetable for a date range (default: current week) |
| Today's schedule with all details |
| Tomorrow's schedule (skips weekends) |
| Timetable for any class at the school (default: student's own class) |
| List all classes at the school (use with |
| Pending homework assignments with due dates |
| Upcoming exams and tests |
| Registered absences with reason, status, and notes |
| Timetable changes: cancellations, substitutions, room and teacher swaps |
| School messages and announcements for a specific date |
| School metadata: period times, holidays, last data import |
All tools are read-only. No data is modified on WebUntis.
🔑 Authentication
This server uses the 2017 mobile API with per-request TOTP authentication, the same mechanism the official Untis Mobile app uses. Each API call generates a fresh one-time password from your QR code secret.
What this means:
No browser login, no SSO flow, no session management
No password stored (unless you choose to provide one)
Works even if your school uses external SSO (Microsoft, Google, Bildungsportal)
The secret is a static key that doesn't expire until you regenerate it
What you need:
Config Variable | Where to Find It | Example |
| QR code dialog: "Url" field |
|
| QR code dialog: "Schule" field |
|
| QR code dialog: "Benutzer" field |
|
| QR code dialog: "Schlüssel" field |
|
| Your child's first name |
|
If you have multiple children at the same school, WEBUNTIS_STUDENT selects which child's data to show. It matches against the first name.
🔒 Security and Privacy
Credentials never leave your machine. They are passed as environment variables to the MCP process and used only to authenticate with your school's WebUntis server.
No telemetry, no analytics, no cloud. This is a local tool.
Read-only. This server cannot modify any data on WebUntis.
No credentials in the code. Ever. The repository contains zero secrets.
MIT licensed. You can read every line of code.
Store your credentials securely. Environment variables in your MCP client config are readable by the MCP process only. Do not commit them to version control. Do not share your QR code secret.
🐍 Using as a Python Library
The WebUntisClient class works standalone, without MCP. Use it to build your own scripts, notification services, or integrations.
from webuntis_mcp.client import WebUntisClient
client = WebUntisClient(
server="yourschool.webuntis.com",
school="yourschool",
username="parent@example.com",
secret="ABCDEF1234567890",
student="kid1",
)
client.login()
# Get tomorrow's timetable
from datetime import date, timedelta
tomorrow = date.today() + timedelta(days=1)
periods = client.get_timetable(tomorrow, tomorrow)
for p in periods:
print(f"{p.start_time} {p.subject} in {p.room} ({p.teacher})")
# Check for homework
homework = client.get_homework(days_ahead=7)
for hw in homework:
print(f"Due {hw.date_due}: [{hw.subject}] {hw.text[:80]}")
# Check absences
absences = client.get_absences()
for a in absences:
print(f"{a.start_date}: {a.reason} ({a.excuse_status})")
# List all classes and get another class's timetable
klassen = client.get_klassen()
for k in klassen:
print(f"{k.name} ({k.long_name})")
other_class = client.get_class_timetable(class_name="2a", start_date=tomorrow, end_date=tomorrow)
for p in other_class:
print(f"{p.start_time} {p.subject} in {p.room}")
# School info
info = client.get_school_info()
print(f"School: {info.school_name}, Year: {info.school_year}")
print(f"Last data import: {info.last_import}")Use cases for the library:
Build a Telegram or Signal bot that alerts you about schedule changes
Create a dashboard showing the week's timetable
Write a cron job that emails you when homework is assigned
Integrate school data into Home Assistant or other automation platforms
🏗️ Architecture
How It Works
The server authenticates with your school's WebUntis instance using TOTP
It resolves your child's internal student ID from the parent account
Each tool call uses per-request TOTP authentication (same as the official mobile app)
The first call fetches master data (subjects, teachers, rooms, classes) and caches it
Subsequent calls are fast since only timetable data needs to be fetched
API Endpoints Used
All calls go through the 2017 mobile API (/WebUntis/jsonrpc_intern.do), the same endpoint the official Untis Mobile app uses:
getUserData2017, getTimetable2017, getHomeWork2017, getExams2017, getStudentAbsences2017, getMessagesOfDay2017
Parent Account Limitations
WebUntis uses role-based access control. Parent accounts (type 12, "Legal Guardian") have restricted access compared to student or teacher accounts:
Feature | Status | Notes |
Own child's timetable | ✅ Works | Via student ID from login response |
Own child's class timetable | ✅ Works | Includes all groups and subjects |
Any class's timetable | ✅ Works | Use |
Homework | ✅ Works | Via 2017 mobile API |
Exams | ✅ Works | Via 2017 mobile API |
Absences | ✅ Works | Read-only via 2017 mobile API |
Teacher list | ❌ Blocked | Teacher names come from timetable data instead |
Student list | ❌ Blocked | Student ID comes from login response instead |
Substitution list | ❌ Blocked | Changes are visible in timetable period data |
Messages/Announcements | ✅ Works | Via |
What This Server Does NOT Do
No write operations. It cannot create absences, send messages, or modify any data.
No notifications. It provides data on request. Your AI agent or a separate tool handles delivery (Telegram, email, calendar, etc.).
No calendar integration. The agent can read schedule data and use other tools to create calendar events.
🔧 Setup Command
The webuntis-mcp setup command helps you configure the server without editing JSON files manually.
Interactive Mode
webuntis-mcp setupWalks you through:
Searching for your school by name or city
Entering your credentials (username + QR code secret)
Testing the login
Selecting your child (if multiple, shows name and class)
Saving credentials to
~/.config/webuntis-mcp/config.env(asks Y/n, default: save)
Non-Interactive Mode
For scripts and AI agents:
webuntis-mcp setup \
--school "Example School" \
--username "parent@example.com" \
--secret "ABCDEF1234567890" \
--student "kid1" \
--jsonSaves the config file automatically and returns a JSON status object:
{
"status": "ok",
"server": "example.webuntis.com",
"school": "example",
"student": "kid1",
"class": "1A",
"config_file": "~/.config/webuntis-mcp/config.env",
"mcp_config": {
"mcpServers": {
"webuntis-mcp": {
"command": "webuntis-mcp"
}
}
}
}On error, returns {"status": "error", "error": "..."} with a non-zero exit code.
AI agents can run the setup command and then add the simple mcp_config entry to the user's settings. No env vars needed since credentials are in the config file.
❓ FAQ
Q: Does this work with any school? A: Yes, any school that uses WebUntis. The server and school name differ per institution, but the API is the same everywhere.
Q: Do I need a student account? A: No. A parent (legal guardian) account is sufficient for all features this server provides.
Q: Does my school use SSO? Will this still work? A: Yes. The TOTP authentication bypasses SSO entirely. It uses the same mechanism as the official Untis Mobile app.
Q: What if I have multiple children at the same school?
A: Set WEBUNTIS_STUDENT to the first name of the child you want data for. Currently, each MCP instance supports one child. For multiple children, run multiple instances with different configs.
Q: Is my password needed? A: No. The QR code secret (TOTP key) is sufficient for all read operations. Your password is never required.
Q: How often can I query the API? A: WebUntis has rate limiting. Normal usage (a few queries per hour) is fine. Avoid polling more frequently than every 10 minutes.
Q: Can the school see that I'm using this? A: WebUntis logs API access. Your queries appear as Untis Mobile app requests. This is the same as using the official app.
📋 Configuration Reference
The recommended way to configure is webuntis-mcp setup, which creates the config file automatically.
Config file (created by setup): ~/.config/webuntis-mcp/config.env
WEBUNTIS_SERVER=yourschool.webuntis.com
WEBUNTIS_SCHOOL=yourschool
WEBUNTIS_USERNAME=parent@example.com
WEBUNTIS_SECRET=ABCDEF1234567890
WEBUNTIS_STUDENT=kid1All configuration variables:
Variable | Required | Description |
| Yes | WebUntis server hostname (e.g. |
| Yes | School short name as shown in QR code dialog |
| Yes | Your login (usually email address) |
| Yes | 16-character TOTP key from QR code dialog |
| Yes | Child's first name (for student resolution) |
| No | Login password (not needed for read-only, reserved for future write support) |
Environment variables take precedence over the config file. This allows overriding individual values without editing the file.
🙏 Acknowledgments
This project was inspired by and learned from:
BetterUntis by SapuSeven (MIT License). His clean implementation of the 2017 mobile API, per-request TOTP authentication, and masterData caching taught us the modern way to talk to WebUntis. The API patterns, method signatures, and response parsing in our code are directly informed by studying his Kotlin source. No code was copied.
homeassistant-WebUntis by Jonas (MIT License). His work on TOTP authentication for parent accounts and timetable change detection was invaluable during early API exploration.
python-webuntis (BSD License). The original Python WebUntis library, useful as an API reference.
⚖️ Disclaimer
This project is not affiliated with, endorsed by, or connected to Untis GmbH or the WebUntis platform in any way. WebUntis is a registered trademark of Untis GmbH.
This tool accesses the WebUntis API as an end user, using the same authentication mechanism as the official Untis Mobile application. It performs read-only operations with the user's own credentials. Use responsibly and in accordance with your school's acceptable use policies.
Available Tools
11 toolsget_absencesC
Fetch registered absences for the student.
Shows absence records with dates, times, reasons, excuse status, and any notes attached.
Args: start_date: Start date in YYYY-MM-DD format (default: school year start) end_date: End date in YYYY-MM-DD format (default: school year end)
Inputs: end_date, start_date. Returns: result
get_changesA
Detect timetable changes like cancellations, substitutions, and room swaps.
Filters the timetable for lessons that have been modified from the original schedule.
Args: start_date: Start date in YYYY-MM-DD format (default: today) end_date: End date in YYYY-MM-DD format (default: start + 4 days)
Inputs: end_date, start_date. Returns: result
get_class_timetableA
Fetch a class timetable. Can show any class at the school, not just the student's own.
Useful for seeing religious instruction, split groups, comparing schedules between classes, or checking a friend's class. Use list_classes to discover available class names.
Args: class_name: Class name like '1a', '2b', '3c' (default: student's own class) start_date: Start date in YYYY-MM-DD format (default: today) end_date: End date in YYYY-MM-DD format (default: start + 4 days)
Inputs: end_date, class_name, start_date. Returns: result
get_examsA
Fetch upcoming exams and tests.
Args: days_ahead: Number of days to look ahead (default: 30)
Inputs: days_ahead. Returns: result
get_homeworkB
Fetch pending homework assignments.
Returns homework with subject, teacher, description text, and due date.
Args: days_ahead: Number of days to look ahead (default: 14)
Inputs: days_ahead. Returns: result
get_messagesB
Fetch messages of the day from the school.
Returns announcements, notices, and information messages published by the school for a specific date.
Args: target_date: Date in YYYY-MM-DD format (default: today)
Inputs: target_date. Returns: result
get_school_infoA
Fetch school metadata including period times, holidays, and last data import.
Useful for understanding the school's schedule structure and upcoming free days.
Inputs: no named parameters. Returns: result
get_timetableA
Fetch the student's timetable for a date range.
Returns lessons with subject, room, teacher, and any changes (cancellations, substitutions, room swaps).
Args: start_date: Start date in YYYY-MM-DD format (default: today) end_date: End date in YYYY-MM-DD format (default: start + 4 days)
Inputs: end_date, start_date. Returns: result
get_todayA
Fetch today's schedule with all details.
Shows all lessons for today including any cancellations, substitutions, room changes, and teacher changes.
Inputs: no named parameters. Returns: result
get_tomorrowA
Fetch tomorrow's schedule.
Shows all lessons for the next school day. If tomorrow is a weekend, returns the next Monday's schedule.
Inputs: no named parameters. Returns: result
list_classesA
List all classes at the school for the current school year.
Returns class names that can be used with the get_class_timetable tool to fetch any class's schedule.
Inputs: no named parameters. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
get_today and get_tomorrow are essentially convenience wrappers around get_timetable with fixed date ranges, and get_changes overlaps with get_timetable (whose description already promises cancellations/substitutions/room swaps). Descriptions provide useful context, but an agent must still reason about when to prefer the specialized tool over the general one.
Nearly every tool follows the get_<noun> pattern (get_timetable, get_homework, get_exams, etc.), with list_classes as the only variant, which is still a clean verb_noun convention. No mixing of camelCase/snake_case or vague verbs.
11 tools is well-scoped for a school information server, with each covering a distinct data domain (timetable, homework, exams, absences, messages, metadata). No padding or redundancy at the count level.
The surface covers the core student life domains: schedules, classes, homework, exams, absences, messages, and school metadata. Grades/report cards and any write operations (e.g., excusing absences) are absent, but read-only coverage is largely complete.
Related MCP Connectors
Let your AI agent read and act on your Mail, Calendar, Contacts and more. Works with iCloud.
Your Telegram, WhatsApp, Instagram, mail and calendar in Claude or ChatGPT. Never sends messages.
Connects AI assistants to TrackingTime for querying time entries, projects, tasks, customers, and team data using natural language.
Read, summarize and send your own WhatsApp messages from AI assistants (OAuth 2.1).
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceEnables accessing IServ school platform features such as timetable, exercises, messenger, and more via natural language, without exposing credentials to agents.1MIT
- FlicenseNot gradedqualityCmaintenanceEnables AI clients to access and query WebUntis school data, including timetables, homework, exams, absences, and more via MCP tools.-
- AlicenseAqualityBmaintenanceEnables AI assistants to access Librus Synergia school data, including grades, attendance, timetables, homework, calendar, announcements, messages, formative assessments, school-year history, class-free days, and student information. Supports multiple logins and self-hosted HTTP access for agents on other machines.32595 PyPI15MIT
- AlicenseNot gradedqualityBmaintenanceLets AI assistants query a family's school grades, absences, timetable, messages, trips, and calendar, and—after explicit human confirmation—report or justify absences, answer authorizations, reply to teachers, and book meetings.MIT