EduPage MCP Server

Project

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
• Contributing
• Limitations
• Support
• License

Why another EduPage MCP server?

Three EduPage MCP servers exist. All three wrap the same community-maintained edupage-api library — none of them reimplements EduPage's undocumented endpoints from scratch. I have no affiliation with the other two; they are listed here because an honest comparison is more useful than a marketing page.

Two things worth stating plainly before the feature table. This is the newest and least-adopted of the three — as of 2026-09-28 it is 25 days old with a single star, while mhlavac/edupage-mcp predates it by over six months. And tool count is a poor metric: this project deliberately folds families behind a discriminating parameter (get_roster(roster_type=…), get_timeline(category=…)) rather than shipping near-identical tools, so its 29 tools cover ground that takes the others 26 or 13 separate ones. The table below is therefore written by capability, not by tool name.

Capabilities

Where the other two are genuinely better

The table above is not one-sided, and it would be dishonest to leave it there:

mhlavac/edupage-mcp

• get_school_days — answers "is my kid at school today / over lunch?" from trips, excursions and absences. This project has no equivalent tool.
• Cross-school merged queries. Its list-returning tools merge across schools, tag every row with a school field, and accept a school= filter. Here, subdomain selects a single school, and a few tools (for example get_student_timetable) return one result per school instead of merging.
• Broader read surface on paper — 26 distinct tools where this project folds the same ground into parameterised families. If you like one-tool-per-endpoint, that is a legitimate preference, not a flaw.
• Ships a .mcp.json for zero-config Claude Code pickup.

mrtineu/edupage-mcp

• By far the deepest homework support of the three. It parses the internal material-player page, so you get the assignment body plus a list of attachments, and download_homework_file saves the file to disk. This project's get_timeline(category='homework') — like mhlavac's — only sees what the timeline notification itself exposes. This is a real gap here.
• Fails loudly on 2FA. It detects a pending 2FA and raises a clear error telling you 2FA is unsupported. mhlavac discards the library's return value and would report success with a non-authenticated session. This project goes further and actually completes the flow.
• Async-native tool bodies, and one-command uvx install without a clone (this project matches the install story, and is additionally in the MCP Registry).

What only this project does

• 2FA completion, and login from an existing PHPSESSID session.
• Parent session-switching into a child account — and back to the parent.
• The full canteen write surface: choose_meal, sign_off_meal, rate_meal.
• Timetables addressed by teacher or classroom, and over a date range.
• get_next_ringing_time — the next bell, live.
• custom_request — a raw passthrough for any endpoint no tool covers yet.
• Role detection, so a parent, a student and a teacher each get the right behaviour from the same tool.
• get_day_summary — one call for a whole day: timetable, substitutions, meals, homework, absences, news and events.

Which one should you pick?

• You want the broadest read surface and do not need any write operation → mhlavac/edupage-mcp.
• You care about homework content and files, or want the simplest possible install → mrtineu/edupage-mcp.
• You need writes (meal ordering, messages, child switching), 2FA, or a raw passthrough → this project.

Comparison checked against each project's source, GitHub metadata and PyPI on 2026-09-28. These projects move fast — if a row is wrong, please open an issue rather than assuming it is deliberate.

What it provides

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

• Authentication — login (by credentials, portal auto-detect, or a PHPSESSID cookie via method=), login_all (multi-school, one call), two_factor_finish (complete a pending 2FA), get_subdomains (schools available to the account with role/user id per school + env config, live subdomain discovery for parents). The former auth_status, user_id, login_auto, login_from_session, and two_factor_check_confirmed tools are folded into these.
• Timetables — get_my_timetable, get_timetable (teacher/student/class/ classroom; end_date for a range, formerly get_timetable_range), get_student_timetable (student by name, cross-school), get_next_week_timetable, get_next_ringing_time, get_periods, get_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_subdomains (subdomains available to the account — live-discovered for parents, limited by EDUPAGE_SUBDOMAINS when set — plus session state per school)
• Grades — get_grades
• Timeline / notifications — get_timeline (category= for homework, assignments, absences, events, news, or full history since a date)
• Substitutions — get_timetable_changes, get_missing_teachers
• Meals — get_meals, choose_meal, sign_off_meal, rate_meal
• Day summaries — get_day_summary (one call: timetable, substitutions, missing teachers, grades, meals, homework, assignments, absences, news, events, notifications for a date — "what happened yesterday at school" in a single round trip; each section is isolated so one failure doesn't kill the report). Includes an OpenCode skill (school-day-summary) for human-readable formatting in OpenCode; other clients use the raw JSON directly.
• Rosters — get_roster (roster_type= for students, all students, teachers, classes, classrooms, or subjects), get_my_students
• Actions — send_message, switch_to_student, switch_to_parent, custom_request

Getting started

You need 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 MCP Registry (recommended, one-click in VS Code / GitHub Copilot)

The server is listed in the MCP Registry. In VS Code or GitHub Copilot, search for "EduPage MCP" and install with one click. Or use the direct deeplink: mcp://install/io.github.oliverhruby/edupage-mcp

Option B — from PyPI

Use this for normal usage with a released version.

Requirements: uv for uvx, or Python 3.10+ for pip.

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 C — from GitHub (latest source)

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

Requirements: uv for uvx, or Python 3.10+ for pip.

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 D — Docker

Use this for an isolated container runtime.

Requirements: Docker.

Pull a prebuilt image (recommended):

docker pull ghcr.io/oliverhruby/edupage-mcp:latest

docker run --rm -i \
  -e EDUPAGE_USERNAME=your_username \
  -e EDUPAGE_PASSWORD=your_password \
  ghcr.io/oliverhruby/edupage-mcp:latest

Version tags are also available (for example v0.4.0) if you prefer pinned images.

Build locally from source (fallback):

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.

Option C — development from source

Use this if you are contributing or debugging locally.

Requirements: Python 3.10+.

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.

Requirements: Docker.

Pull a prebuilt image (recommended):

docker pull ghcr.io/oliverhruby/edupage-mcp:latest

docker run --rm -i \
  -e EDUPAGE_USERNAME=your_username \
  -e EDUPAGE_PASSWORD=your_password \
  ghcr.io/oliverhruby/edupage-mcp:latest

Version tags are also available (for example v0.4.0) if you prefer pinned images.

Build locally from source (fallback):

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 "school1,school2,school3"   # Windows
export EDUPAGE_SUBDOMAINS="school1,school2,school3" # macOS / Linux

get_subdomains   # lists school1, school2, school3 (logged in, with role)
scan_students      # discovers Student A and Student B across those schools
get_student_timetable name="Student A"   # is found at school1 AND school2

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="school1,school2" usernames="u1,u2" passwords="p1,p2"

get_my_timetable subdomain="school1"
get_my_timetable subdomain="school2"
get_subdomains         # 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 Student A")

Because the server auto-discovers students across the configured EDUPAGE_SUBDOMAINS (or every logged-in school when the variable is unset), 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 in scope:

"timetable for Student A"  ->  get_student_timetable name="Student A"

get_student_timetable (with no subdomain):

1. searches every school in the discovery scope — the configured EDUPAGE_SUBDOMAINS, or all logged-in schools when unset — 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. Student at school1 + school2) therefore yields a list of two per-school timetables — separate results, never merged. This is the built-in replacement for maintaining a manual "Student → school1" 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_timeline categories homework, assignments, absences, events and news derive their data from the timeline notifications — if the school doesn't push certain event types, those categories 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.
• get_meals first tries the per-student meal-ordering endpoint (needed for ordering/ratings). When a school doesn't enable that, it falls back to the school's public canteen menu widget (/menu/?wid=menu_CanteenMenu_1). All five slots (breakfast/snack/lunch/afternoon_snack/dinner) are always returned; slots the school doesn't publish are None.

Skills

The package includes an OpenCode skill (school-day-summary) at <site-packages>/edupage_mcp/skills/school-day-summary/SKILL.md. It teaches OpenCode agents how to turn get_day_summary JSON into a human-readable daily school report.

OpenCode only: To register it:

mkdir -p ~/.config/opencode/skills/school-day-summary
cp <site-packages>/edupage_mcp/skills/school-day-summary/SKILL.md \
   ~/.config/opencode/skills/school-day-summary/SKILL.md

Restart OpenCode; the agent can then answer "what happened at school yesterday for my kids?" by calling get_day_summary per child.

Other MCP clients (Copilot, Claude, Cursor, etc.) — call get_day_summary directly; they receive the full structured JSON. Formatting is client-specific (no skill system in the MCP protocol).

Contributing

Contributor and maintainer guidance is in CONTRIBUTING.md.

• Contribution workflow and local setup
• Architecture and implementation details
• Release process (PyPI, GitHub Releases, GHCR)
• CI quality gates and upstream coverage drift checks

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 method="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.

Support

If you like this project and want to support or request a feature, send me a beer, it keeps my mind relaxed and ideas will come :-)

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