edupage-mcp-full

A Model Context Protocol (MCP) server that exposes the full functionality of the edupage-api Python library to AI agents such as opencode, Claude, Cursor and any other MCP client.

EduPage is a school information system used across Europe. This server lets you query and operate a student / teacher / parent EduPage account directly from your agent: timetables, grades, homework, substitutions, meals (including ordering), messages, rosters, parent child-switching and more — including multiple schools (e.g. two children attending different schools).

⚠️ Unofficial API. Like all EduPage MCP servers, this relies on the community-maintained edupage-api library, which talks to EduPage's undocumented endpoints. Use read-only features freely; use the write features (send_message, meal ordering, child switching) carefully.

Table of Contents

• Why another EduPage MCP server?
• What it provides
• Getting started
  • Prerequisites
  • 1. Install
  • 2. Configure credentials
  • 3. Register with your MCP client
• Usage examples
• Multiple schools (subdomains)
• Tool reference
• Data & safety notes
• Architecture & implementation
• Limitations
• License

Why another EduPage MCP server?

Two other EduPage MCP servers already exist:

• mrtineu/edupage-mcp — also published on PyPI as edupage-mcp
• mhlavac/edupage-mcp

Both are good and I have no affiliation with them — they are simply referenced here for honest comparison. They primarily focus on the read-only surface of the API.

This project deliberately goes further:

Key differentiators:

• Multi-school automatic discovery. Set EDUPAGE_SUBDOMAINS with one shared login and the server auto-discovers students across all schools — no need to maintain a manual "Viktor → school A, Tamara → school B" mapping. A student at two schools (e.g. Tamara at iprskola + cvcmalacky) is found automatically with separate per-school results.
• Role-aware tools. The server detects whether you're a parent, student, or teacher at each school and behaves accordingly — get_student_timetable switches to the student account for parents, returns direct timetables for students. No tool duplication.
• Full write surface. Meal ordering/rating, message sending, student switching — the other servers don't cover these.
• OIDC publishing. No PyPI token to manage. Push a tag and GitHub Actions publishes via OIDC trusted publishing.

What it provides

A single stdio MCP server exposing 43 tools (published on PyPI as edupage-mcp-full):

• Authentication — login, login_auto, login_all, login_from_session, two_factor_check_confirmed, two_factor_finish, auth_status, user_id
• Timetables — get_my_timetable, get_timetable (teacher/student/class/ classroom), get_student_timetable (student by name, cross-school), get_next_week_timetable, get_next_ringing_time, get_periods, school_year
• Students — find_student (name → person_id, cross-school), get_student_timetable (cross-school, role-aware), scan_students (auto-discover all students across schools), get_my_students (classmates or school-wide for parents), switch_to_student (by id or name, parent only), switch_to_parent
• Schools — get_schools (logged-in schools with role per school)
• Grades — get_grades
• Notifications / timeline — get_notifications, get_notification_history, get_homework, get_assignments, get_absences, get_upcoming_events, get_news
• Substitutions — get_timetable_changes, get_missing_teachers
• Meals — get_meals, choose_meal, sign_off_meal, rate_meal
• Rosters — get_students, get_all_students, get_teachers, get_classes, get_classrooms, get_subjects, get_my_students
• Actions — send_message, switch_to_student, switch_to_parent, custom_request

Getting started

Prerequisites

• Python 3.9+ (Python 3.14 on Windows is verified)
• A GitHub account only if you want the repo; not needed to run.
• An MCP-capable client (opencode, Claude Desktop, Cursor, etc.)

1. Install

Option A — from PyPI (recommended):

uvx edupage-mcp-full
# or, if you prefer pip (into whatever environment your MCP client uses):
pip install edupage-mcp-full

uvx runs the package without installing it — this is the canonical way MCP servers are launched. uv is required for uvx (install with pip install uv or winget install astral-sh.uv).

Option B — from GitHub (latest source):

uvx --from "git+https://github.com/oliverhruby/edupage-mcp.git" edupage-mcp-full
# or
pip install "git+https://github.com/oliverhruby/edupage-mcp.git"

Option C — development from source:

git clone https://github.com/oliverhruby/edupage-mcp.git
cd edupage-mcp
uv sync               # or: python -m venv .venv && .venv/bin/python -m pip install -e .
uv run edupage-mcp-full

pyproject.toml pins mcp<2 (the stable FastMCP v1 API). mcp 2.x renamed FastMCP to MCPServer and changed the API surface; this server targets the FastMCP v1 API for simplicity and stability.

Releases

New versions are published to PyPI automatically via GitHub Actions using OpenID Connect trusted publishing (no manual token). Pushing a tag such as v0.1.0 triggers the publish workflow (see .github/workflows/publish.yml for the one-time PyPI registration). version in pyproject.toml must match the tag.

2. Configure credentials

Either set environment variables or pass credentials to login (see Usage).

# Windows (persistent, per-user)
setx EDUPAGE_USERNAME "your_username"
setx EDUPAGE_PASSWORD "your_password"
setx EDUPAGE_SUBDOMAIN "your_school"     # single school: https://your_school.edupage.org
setx EDUPAGE_SUBDOMAINS "s1,s2,s3"       # multiple schools: auto-login + child discovery

# macOS / Linux
export EDUPAGE_USERNAME="your_username"
export EDUPAGE_PASSWORD="your_password"
export EDUPAGE_SUBDOMAIN="your_school"
export EDUPAGE_SUBDOMAINS="s1,s2,s3"

EDUPAGE_SUBDOMAIN is the single-subdomain case; for multiple schools use EDUPAGE_SUBDOMAINS (auto-login on startup + automatic child discovery). See Multiple schools & automatic child discovery.

3. Register with your MCP client

opencode — add to ~/.config/opencode/opencode.json (or opencode.jsonc):

{
  "mcp": {
    "edupage": {
      "type": "local",
      "enabled": true,
      "command": ["uvx", "edupage-mcp-full"],
      "env": {
        "EDUPAGE_USERNAME": "{env:EDUPAGE_USERNAME}",
        "EDUPAGE_PASSWORD": "{env:EDUPAGE_PASSWORD}",
        "EDUPAGE_SUBDOMAIN": "{env:EDUPAGE_SUBDOMAIN}"
      }
    }
  }
}

Put credentials in your shell/environment (or a .env) and reference them with {env:VAR}, or hardcode them under env: directly. uvx will auto-provision the package the first time; it must be on your PATH.

Claude Desktop / Cursor — use claude_desktop_config.json / .mcp.json with a mcpServers entry in the standard shape, pointing command/args at the venv python and the edupage_mcp.py path, plus an env block with your credentials.

After editing client config, restart the client so the MCP server is loaded.

Usage examples

# Check the MCP is alive and see which schools are logged in
auth_status

# Log in (uses env vars, or pass explicit args)
login

# If 2FA is enabled:
two_factor_check_confirmed        # approve on device -> True
two_factor_finish                 # then finish

# Your own timetable for today
get_my_timetable

# Timetable for a specific class on a date
get_timetable target_type="class" target_id="9.A" date_str="2026-09-10"

# Next week's timetable
get_next_week_timetable

# Grades (all, or for a term/year)
get_grades
get_grades term="FIRST" year=2026

# Substitutions / changes for today
get_timetable_changes

# Meal menu and order lunch (option #2)
get_meals
choose_meal date_str="2026-09-10" meal_type="lunch" number=2

# Who is in the school + send a message to a teacher
get_teachers
send_message recipient_id="Teacher456" body="Hello!"

# Parent account: see students, then switch to one
get_my_students
switch_to_student student_id=123
get_my_timetable
switch_to_parent

# Students by NAME — auto-discovered across all logged-in schools
# (works even when Viktor and Tamara are at different schools / Tamara at two)
find_student name="Viktor"
get_student_timetable name="Viktor"
get_student_timetable name="Viktor" date_str="2026-09-10"
get_student_timetable name="Tamara"   # returns one result per school where found
scan_students                         # list every student at every school

Multiple schools & automatic student discovery

Each subdomain (school) keeps its own logged-in session. There are two ways to log in to several schools at once:

A) Automatic on startup (recommended). Set EDUPAGE_SUBDOMAINS (a comma-separated list) plus the shared EDUPAGE_USERNAME / EDUPAGE_PASSWORD — the server logs into all of them when it launches, so every tool is immediately ready and students are discoverable across all schools with no login call and no student→school mapping:

setx EDUPAGE_SUBDOMAINS "zssturovamalacky,iprskola,cvcmalacky"   # Windows
export EDUPAGE_SUBDOMAINS="zssturovamalacky,iprskola,cvcmalacky" # macOS / Linux

get_schools        # lists zssturovamalacky, iprskola, cvcmalacky (logged in, with role)
scan_students      # discovers Viktor and Tamara across those schools
get_student_timetable name="Tamara"   # is found at iprskola AND cvcmalacky

B) On demand with login_all. Authenticate several schools at once, then pass subdomain to any data tool (it defaults to the last active subdomain when omitted):

login_all subdomains="zssturovamalacky,iprskola" usernames="u1,u2" passwords="p1,p2"

get_my_timetable subdomain="zssturovamalacky"
get_my_timetable subdomain="iprskola"
auth_status          # shows all logged-in subdomains + which is active

You can also call login once per school to add/lookup sessions incrementally.

EDUPAGE_SUBDOMAIN (singular) env var covers a single school only. For two or more schools use EDUPAGE_SUBDOMAINS (auto-login) or login_all / repeated login calls.

Students by name (e.g. "timetable for Viktor")

Because the server auto-discovers students across all logged-in schools, you don't need to know or state which school a student is in. Just ask for the timetable by name and the server searches every school it's logged into:

"timetable for Viktor"  ->  get_student_timetable name="Viktor"

get_student_timetable (with no subdomain):

1. searches every logged-in school for a student whose first/last/full name matches (scan_students does just the discovery step),
2. for each school where the student is found, switches to the student account if you're logged in as a parent, returns that student's timetable for the date, and switches back to the parent account afterwards,
3. returns one result per school.

A student attending more than one school (e.g. Tamara at iprskola + cvcmalacky) therefore yields a list of two per-school timetables — separate results, never merged. This is the built-in replacement for maintaining a manual "Viktor → zsskola1" mapping: with EDUPAGE_SUBDOMAINS set, discovery is fully automatic.

Tool reference

Data & safety notes

• Most tools are read-only. The ones marked Writes? ✅ mutate EduPage state (sent messages, ordered meals, switched accounts). Use them with care.
• get_homework, get_assignments, get_absences, get_upcoming_events and get_news derive their data from the timeline notifications — if the school doesn't push certain event types, those tools may return empty lists.
• get_missing_teachers is marked experimental upstream (parses HTML from the substitution page) and can raise if a teacher's name no longer matches.
• Meal rate_meal and ordering depend on the school publishing menus with the matching identifiers; not all schools expose ratings.

Architecture & implementation

High-level design

MCP client (opencode / Claude / Cursor ...)
        │  stdio JSON-RPC
        ▼
edupage-mcp-full  (FastMCP server, mcp<2, console entry point edupage-mcp-full)
        │  thin, stateless-per-tool facade
        ▼
edupage-api  (community library, all the EduPage endpoint work)
        ▼
EduPage web services (HTTPS, undocumented endpoints)

This project is deliberately a thin wrapper: 95% of the hard, volatile work — EduPage's undocumented/non-public endpoints, the login flow, 2FA, HTML/JSON parsing — lives in the battle-tested edupage-api library. Our job is to expose that library over MCP cleanly, correctly serialise its data model, and make multi-school + write operations ergonomic.

Key files

Session & state management

The server keeps one Edupage() client per subdomain in a dict:

_clients = {}          # subdomain -> Edupage
_two_factor = {}       # subdomain -> TwoFactorLogin (pending 2FA)
_active_subdomain = None

Every data tool resolves its client with _require_client(subdomain):

def _require_client(subdomain=None):
    sub = subdomain or _active_subdomain
    client = _clients.get(sub)
    if client is None or not client.is_logged_in:
        raise RuntimeError(f"Not logged in for subdomain '{sub}' ...")
    return client

This is what makes multiple schools possible in a single server process — each login/login_all call adds or replaces that subdomain's session instead of clobbering a single global client. When subdomain is omitted, tools fall back to the last subdomain that logged in.

2FA flow

edupage-api returns a TwoFactorLogin object when a second factor is required. We keep it keyed by subdomain and expose two controls:

• two_factor_check_confirmed → polls EduPage to see if the confirmation was approved on a device.
• two_factor_finish → either finish() (device-confirmed) or finish_with_code(code) (email/app code).

Serialisation

edupage-api returns rich dataclasses (Lesson, EduGrade, TimelineEvent, Meal, EduStudent, …) containing nested enums, datetime/time objects and sub-objects. A generic _serialize() converts them to plain JSON:

• datetime / date / time → isoformat()
• Enum → .value
• dataclass → dict of fields (skipping private __ fields)
• dict / list / tuple → recursive
• fallback → str()

This keeps tool output consistent, human-readable and JSON-serialisable so any MCP client can render it without importing edupage-api.

Error handling

Each tool runs through _run(..., error_label), which:

1. Catches edupage_api exceptions (e.g. BadCredentialsException, NotLoggedInException, CaptchaException, SecondFactorFailedException, InvalidChildException).
2. Returns a JSON-RPC result with isError: true and a friendly message that includes the exception type and message, so the agent can tell the user what went wrong instead of crashing.

Dependency isolation

The server uses Python-only deps and is pinned to mcp<2. Both uvx and the pip install -e . dev path keep the package isolated from any unrelated global mcp (e.g. a newer v2.x) install, because each runs in its own environment — see Install.

Limitations

• Unofficial/read-mostly by design. EduPage can change its endpoints at any time; reliability ultimately depends on edupage-api, not this wrapper.
• No CAPTCHA bypass. If EduPage presents a CAPTCHA during login, log in via browser first, then use login_from_session with the resulting PHPSESSID.
• 2FA requires human interaction (approve on device or provide a code).
• Parent/teacher accounts are only partially verified upstream; some parent methods are best-effort.
• The auth session lives for the lifetime of the MCP server process; restarting the client means logging in again.
• Children at different schools require you to tell the agent which subdomain each child is in (the server can't guess it). See Children by name.

License

MIT © Oliver Hrubý

This project is not affiliated with or endorsed by Ascora (EduPage) or by the authors of edupage-api. EduPage is a registered trademark of its respective owner(s).