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
• Prompt examples
• Multiple schools (subdomains)
• Tool reference
• Data & safety notes
• Developer guide
  • Architecture & implementation details
  • Releases
  • Quality gates (PRs)
  • Upstream coverage drift check
• 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 44 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, clear_student_cache (force refresh cached student lists)
• 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.10+ (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

If you are using an AI coding client, a simple prompt is often enough to get started, for example: "Install the EduPage MCP as described in this GitHub repository oliverhruby/edupage-mcp". Most MCP-capable clients can then guide you through the available setup options.

Option A — from PyPI (recommended)

Use this for normal usage with a released version.

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 a persistent install. If uvx is unavailable, install uv first (pip install uv or winget install astral-sh.uv).

Option B — from GitHub (latest source)

Use this if you want the latest changes before a PyPI release.

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

Use this if you are contributing or debugging locally.

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

Option D — Docker

Use this for an isolated container runtime.

docker build -t edupage-mcp-full .

docker run --rm -i \
  -e EDUPAGE_USERNAME=your_username \
  -e EDUPAGE_PASSWORD=your_password \
  edupage-mcp-full

The container uses the same environment variables described in Configure credentials. It also includes a HEALTHCHECK (stdio process liveness by default; local TCP check in HTTP transport modes).

For HTTP transports, set optional runtime vars:

• MCP_TRANSPORT: stdio (default), sse, or streamable-http
• MCP_HOST: bind host (default 127.0.0.1)
• MCP_PORT: bind port (default 8000)
• MCP_API_KEY: optional bearer token for HTTP auth

When MCP_API_KEY is set, HTTP requests must include Authorization: Bearer <key>. If MCP_API_KEY is not set, HTTP endpoints are unauthenticated. For production, prefer proper authentication and TLS via a reverse proxy or API gateway.

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.

2. Configure credentials

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

# Windows (persistent, per-user)
setx EDUPAGE_USERNAME "your_username"
setx EDUPAGE_PASSWORD "your_password"
setx EDUPAGE_SUBDOMAINS "s1,s2,s3"       # optional: multiple schools (auto-login + discovery)

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

Single school? Just set EDUPAGE_USERNAME + EDUPAGE_PASSWORD. The server auto-discovers your school via the EduPage portal on startup — no subdomain needed.

Multiple schools? Add EDUPAGE_SUBDOMAINS (comma-separated). The server logs into all of them on startup with your shared credentials.

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_SUBDOMAINS": "{env:EDUPAGE_SUBDOMAINS}"
      }
    }
  }
}

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.

Prompt examples

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.

Single school? No EDUPAGE_SUBDOMAINS needed — the server auto-discovers your school via the portal on startup. For two or more schools, set EDUPAGE_SUBDOMAINS (auto-login) or use 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.

Developer guide

Contributor and maintainer information starts here. If you only want to run the server, you can stop after the user sections above.

Architecture & implementation details

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.

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.

Quality gates (PRs)

Pull requests targeting main are gated by required GitHub checks:

• quality-gates / python-sanity — compiles src/edupage_mcp/__init__.py and verifies pip install . from source.
• quality-gates / docker-mcp-smoke — builds the Docker image and performs a real MCP stdio handshake (initialize + tools/list).
• security / pip-audit — scans Python dependencies for known CVEs.
• container-security / trivy-image — enforces a vulnerability gate on HIGH/CRITICAL findings while still uploading full-severity SARIF results to GitHub Security.

If a required check fails, the PR cannot be merged until it is fixed or explicitly handled.

Upstream coverage drift check

To keep the wrapper aligned with edupage-api, CI runs .github/workflows/upstream-coverage.yml and verifies that every public Edupage method is either:

• covered by MCP wrapper calls in src/edupage_mcp/__init__.py, or
• explicitly listed in scripts/edupage_api_ignored_methods.json with a reason.

Local run:

python scripts/check_edupage_api_coverage.py

If upstream adds a method, this check fails until you either implement support or intentionally document why it is ignored.

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.
• Cross-school student discovery depends on being logged into all relevant schools (via EDUPAGE_SUBDOMAINS, login_all, or repeated login calls). If a school is not logged in, that student's results from that school cannot be discovered.

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).