EduPage MCP Server

EduPage MCP Server

[GitHub release] [Glama Grade] [Quality gates] [Security] [Container security] [Coverage drift]

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?

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 "Student → school1, Student → school2" mapping. A student at two schools (e.g. Student at school1 + school2) 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.

Comparison checked 2026-09-28. If a row is wrong, please open an issue.

What it provides

A single stdio MCP server exposing 31 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)
• Homework — get_timeline(category='homework') to list assignments (ids in additional_data.superid), get_homework_material to read one assignment's body text, dates and attachment list (the notification alone only carries the title and due date), download_attachment to save one attachment to disk
• 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). A bundled agent skill (school-day-summary) turns that JSON into a human-readable daily report — install it with edupage-mcp-full install-skill (see Skills); every client can also call get_day_summary directly and read the JSON.
• 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 — as an agent plugin (recommended: the server and the skill in one install)

For VS Code, GitHub Copilot and Claude Code this repo ships a plugin that installs the server together with the school-day-summary agent skill:

copilot plugin marketplace add oliverhruby/edupage-mcpcopilot plugin install edupage@edupage-plugins

Claude Code reads the same marketplace:

claude plugin marketplace add oliverhruby/edupage-mcpclaude plugin install edupage@edupage-plugins

opencode, Cursor and Windsurf read Agent Skills but not plugins — for those, and for every other install route, see docs/PLUGINS.md.

Option B — one-shot with APM (the server and the skill in one command, optional, emerging standard)

APM (Agent Package Manager) is an emerging open standard for distributing agent context — think npm for agent skills, MCP servers and instructions. This route is optional: Option A and every route below work exactly as before. If you already use APM (or want to try it), it is the only cross-harness one-shot install here.

1. Install the CLI once. Requirements: git, plus uv for the server runtime.

   • Windows: winget install --id Microsoft.APM -e (or scoop bucket add apm https://github.com/microsoft/scoop-apm; scoop install apm)
   • macOS / Linux: brew install apm
   • Any platform with Python 3.10+: pip install apm-cli
   • Other options: installation docs

2. Install this package:

   bash

   apm install oliverhruby/edupage-mcp

   One command does both:

   • deploys the school-day-summary skill into the harness's skills directory (.claude/skills/, .agents/skills/, ...);
   • writes the uvx edupage-mcp-full stdio server entry into the MCP config of every harness APM detects (Claude Code, GitHub Copilot, Cursor, opencode, Codex, Gemini, Windsurf, Kiro, ...); add --target claude (or another target) to force one harness.

3. Verify:

   bash

   apm mcp list        # server registered?

   apm uninstall oliverhruby/edupage-mcp removes the package and the deployed skill files, but leaves the MCP server entry it wrote into .mcp.json (and other harness configs) — delete that entry yourself if you want it gone.

Credentials are never embedded in the package: set EDUPAGE_USERNAME / EDUPAGE_PASSWORD (and EDUPAGE_SUBDOMAINS for multi-school accounts) before running apm install — see 2. Configure credentials.

Pinning. Append #<sha> (or #<tag> once a release contains apm.yml) to pin an exact revision and silence APM's "dependency unpinned" warning; without a pin, APM records the resolved commit in apm.lock.yaml. Releases up to v0.7.0 predate the manifest, so use a commit sha until the next release.

The Claude Code plugin/marketplace install (Option A) remains supported and unchanged — APM is an additional install route, declared in this repo's apm.yml.

Option C — from MCP Registry (one-click, server only, no skill)

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 D — 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 E — 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# orpip install "git+https://github.com/oliverhruby/edupage-mcp.git"

Option F — 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 G — development from source

Use this if you are contributing or debugging locally.

Requirements: Python 3.10+.

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

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 / Linuxexport 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"   # Windowsexport 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 schoolsget_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.
• download_attachment is the one tool that writes to local disk: it saves into dest_dir (default <tempdir>/homework), takes the name from the server's content-disposition when present, and appends (1), (2), ... rather than overwriting anything. An HTML login/error page is refused instead of being written out as an attachment.
• custom_request returns text only: a binary body is refused with a pointer to download_attachment, and a text body over 60000 characters comes back truncated with an explicit truncated: true.
• 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 ships one agent skill (school-day-summary). It teaches a coding agent how to turn get_day_summary JSON into a human-readable daily school report — "what happened yesterday for my kids?"

Installing the plugin ships this skill together with the server. To install the skill on its own:

# already installed with the server:edupage-mcp-full install-skill
# ...or with nothing but uv:uvx --from edupage-mcp-full edupage-mcp-full install-skill --agent copilot

Each agent it touches prints one line:

installed -> C:\Users\you\.copilot\skills\school-day-summary\SKILL.mdskipped (identical) -> /home/you/.claude/skills/school-day-summary/SKILL.mdskipped (exists, differs, use --force) -> /home/you/.agents/skills/school-day-summary/SKILL.md

Restart your agent afterwards so it picks the skill up.

Options

Where it goes

Re-running is safe: a file that is already identical is reported as skipped (identical), and one that differs is left alone unless you pass --force, so a skill you edited locally is never silently clobbered.

Prefer to place the file yourself? edupage-mcp-full install-skill --print prints the exact path of the bundled SKILL.md in the installed package.

Other MCP clients (Claude, Cursor, or any client without a skill system) can just call get_day_summary directly — they receive the full structured JSON. Formatting is client-specific. The base MCP protocol has no skill concept (an io.modelcontextprotocol/skills extension is specified, but this server does not implement it yet), which is why distribution goes through the plugin and the installer above. See docs/PLUGINS.md for every install route.

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

[Support via PayPal]

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