Skip to main content
Glama

Edupage MCP Server

MCP server that connects Claude to Edupage — a school information system used across Europe. Provides access to timetables, grades, homework, messages, students, teachers, and more.

Quick Setup

1. Install

cd /path/to/edupage-mcp
uv sync

Or if you prefer a one-liner without cloning:

uv pip install "mcp>=1.2.0" "edupage-api>=0.12.3"

2. Configure for Claude Code

The easiest way — just open the project folder and the .mcp.json will be picked up automatically. Set environment variables first:

export EDUPAGE_USERNAME=your_user
export EDUPAGE_PASSWORD=your_pass
export EDUPAGE_SUBDOMAIN=your_school

Or add the server manually:

claude mcp add edupage -- uv run --directory /path/to/edupage-mcp python -m edupage_mcp

With auto-login via environment variables:

claude mcp add --env EDUPAGE_USERNAME=your_user --env EDUPAGE_PASSWORD=your_pass --env EDUPAGE_SUBDOMAIN=your_school edupage -- uv run --directory /path/to/edupage-mcp python -m edupage_mcp

3. Configure for Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "edupage": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/edupage-mcp", "python", "-m", "edupage_mcp"],
      "env": {
        "EDUPAGE_USERNAME": "your_username",
        "EDUPAGE_PASSWORD": "your_password",
        "EDUPAGE_SUBDOMAIN": "your_school"
      }
    }
  }
}

4. Configure for Cowork

Use the .mcp.json file included in this repo — just set the environment variables.

Related MCP server: io.github.thehesiod/psquare

Authentication

Two options:

  1. Environment variables (recommended) — set EDUPAGE_USERNAME, EDUPAGE_PASSWORD, and EDUPAGE_SUBDOMAIN. The server logs in automatically at startup.

  2. Manual login tool — call the login or login_auto tool at the start of your session.

The subdomain is the part before .edupage.org in your school's URL (e.g. myschool for https://myschool.edupage.org).

Available Tools

Tool

Description

login

Log in with username, password, subdomain

login_auto

Log in via portal (auto-detect school)

get_timetable

Get timetable for a date

get_next_week_timetable

Get Mon-Fri timetable for next week

get_timetable_changes

Get substitutions / changes for a date

get_grades

Get student grades/marks

get_students

Get students in your class

get_all_students

Get all students in the school

get_teachers

Get all teachers

get_classes

Get all classes

get_classrooms

Get all classrooms

get_homework

Get homework assignments

get_assignments

Get all assignments (homework, tests, etc.)

get_timeline

Get recent timeline items

get_notifications

Get recent notifications

get_notification_history

Get notifications since a date

get_news

Get school news

get_meals

Get meal info incl. rating window, averages, your scores

rate_meal

Rate a meal (quality + quantity, 1–5) — writes to EduPage

send_message

Send a message to users

get_subjects

Get all subjects

get_periods

Get bell schedule / periods

get_my_children

Get children linked to a parent account

get_absences

Get student absences

get_upcoming_events

Get upcoming school events

get_student_summary

All-in-one summary: grades, homework, exams, absences

Project Structure

edupage-mcp/
├── CLAUDE.md              # Developer guide
├── FORK.md                # Fork notes / upstream attribution
├── pyproject.toml         # Package config (uv/hatch)
├── .mcp.json              # Claude Code project config
├── env.example            # Example environment variables
└── src/
    └── edupage_mcp/
        ├── __init__.py
        ├── __main__.py
        ├── meals.py       # Menu board + rating helpers
        └── server.py      # MCP server implementation

Meal ratings

get_meals returns (per snack/lunch/afternoon_snack when present):

  • menu choices (menus[] with code A/B/… and dishes)

  • ordered_meal, serving window, order deadlines

  • rating_open, rate_from, rate_until

  • per-menu rating: class averages + my_quality / my_quantity when you already rated

rate_meal posts to EduPage ulozHodnotenia:

quality=1..5  quantity=1..5  date_str=YYYY-MM-DD  meal_type=lunch  menu_number=1

Default meal_type is lunch. Empty menu_number uses the ordered menu (else first menu).

Development

Run the server directly for testing:

uv run python -m edupage_mcp

Test with MCP Inspector:

npx @modelcontextprotocol/inspector uv run python -m edupage_mcp

Dependencies

  • mcp >= 1.2.0 — Model Context Protocol Python SDK

  • edupage-api >= 0.12.3 — Unofficial Edupage API client (GitHub)

Notes

  • The server uses stdio transport (reads stdin, writes stdout)

  • All logging goes to stderr to avoid corrupting the MCP protocol

  • Session persists for the lifetime of the server process

  • The send_message tool sends real messages — use with care

  • If Edupage requests a CAPTCHA, log in via browser first then retry

License

This project is licensed under the GPL-3.0-or-later — see the LICENSE file for details.

The edupage-api dependency is GPL-3.0 licensed, which requires derivative works to use a compatible license.

Available Tools

26 tools
get_absencesA

Get absence records from the last N days.

Args: since_days: How many days back to search (default 30) student_name: Optional student name to validate context (e.g. 'Jan Novak'). Searches all schools automatically. school: School subdomain (only needed with multiple schools and no student_name).

Returns: JSON array of absence records with date, type, text, author

Inputs: school, since_days, student_name. Returns: result

get_all_studentsA

Get all students in the school (name + class only).

Args: school: School subdomain (only needed with multiple schools).

Returns: JSON array of student skeletons

Inputs: school. Returns: result

get_assignmentsA

Get all assignments (homework, tests, exams, projects, etc.) from the last N days.

Args: since_days: How many days back to search (default 30) status: Filter by status — "active", "done", or "" (all, default) event_type: Narrow to specific types (comma-separated). Valid types: homework, etesthw, bexam, sexam, oexam, rexam, pexam, testing school: School subdomain (only needed with multiple schools).

Returns: JSON array of assignment items

Inputs: school, status, event_type, since_days. Returns: result

get_classesA

Get all classes in the school.

Args: school: School subdomain (only needed with multiple schools).

Returns: JSON array of lean class records

Inputs: school. Returns: result

get_classroomsA

Get all classrooms in the school.

Args: school: School subdomain (only needed with multiple schools).

Returns: JSON array of lean classroom records

Inputs: school. Returns: result

get_gradesA

Get student grades/marks. Returns grades for the current session's child. For parent accounts with multiple children, grades are for the child linked to the current session.

Args: term: Term/semester filter (leave empty for all) year: School year filter (leave 0 for current) school: School subdomain (only needed with multiple schools).

Returns: JSON array of lean grade records with percent, class_avg, etc.

Inputs: term, year, school. Returns: result

get_homeworkA

Get homework assignments from the last N days. Extracts homework from the timeline/notification history.

Args: since_days: How many days back to search (default 30) status: Filter by status — "active" (not done), "done", or "" (all, default) school: School subdomain (only needed with multiple schools).

Returns: JSON array of homework items with title, subject, due_date, etc.

Inputs: school, status, since_days. Returns: result

get_mealsA

Get school meal information for a given date (defaults to today).

Includes menu choices, order state, rating window, class averages, and your own scores when already submitted (my_quality / my_quantity).

Args: date_str: Date in YYYY-MM-DD format. Leave empty for today. school: School subdomain (only needed with multiple schools).

Returns: JSON of meal data (snack, lunch, afternoon_snack) plus rating fields

Inputs: school, date_str. Returns: result

get_my_childrenA

Get your children (for parent accounts) or classmates (for student accounts). Use this to find student names for use with other tools like get_timetable, get_absences, and get_student_summary.

Args: school: School subdomain (only needed with multiple schools).

Returns: JSON array of students with person_id, name, class_id, number

Inputs: school. Returns: result

get_newsB

Get school news from the Edupage webpage.

Args: school: School subdomain (only needed with multiple schools).

Returns: JSON array of news items

Inputs: school. Returns: result

get_next_week_timetableA

Get timetable for each day of the upcoming week (Mon-Fri).

Args: class_name: Class name (e.g. '6e', '4a'). If empty, uses logged-in user's timetable. student_name: Student name to look up their class timetable (searches all schools). school: School subdomain (only needed with multiple schools and no student_name).

Returns: JSON object keyed by date with lean timetable lessons

Inputs: school, class_name, student_name. Returns: result

get_notification_historyA

Get notification history since a given date.

Args: since_date: Start date in YYYY-MM-DD format. Defaults to 7 days ago. status: Filter — "active", "done", or "" (all, default). starred: Filter — "yes", "no", or "" (all). event_type: Raw type filter (comma-separated). category: Category filter: homework, grades, exams, messages, absences, events, news. limit: Max items (default 50). offset: Skip items for pagination. include_system: Include system events (default false). school: School subdomain (only needed with multiple schools).

Returns: JSON array of lean notification events

Inputs: limit, offset, school, status, +5 more. Returns: result

get_notificationsA

Get recent notifications. System events are hidden by default.

Args: status: Filter — "active", "done", or "" (all, default). starred: Filter — "yes", "no", or "" (all). event_type: Raw type filter (comma-separated). category: Category filter: homework, grades, exams, messages, absences, events, news. limit: Max items (default 50). offset: Skip items for pagination. include_system: Include system events (default false). school: School subdomain (only needed with multiple schools).

Returns: JSON array of lean notification events

Inputs: limit, offset, school, status, +4 more. Returns: result

get_periodsA

Get school period / bell schedule information.

Args: school: School subdomain (only needed with multiple schools).

Returns: JSON array of periods with start/end times

Inputs: school. Returns: result

get_studentsB

Get students in your class.

Args: school: School subdomain (only needed with multiple schools).

Returns: JSON array of lean student records

Inputs: school. Returns: result

get_student_summaryA

Get a comprehensive summary for a student: grades, homework, exams, absences, and messages — all in one call.

Args: student_name: Student name (e.g. 'Jan Novak'). Use get_my_children() to find names. Searches all schools automatically. since_days: How many days back to include (default 14) school: School subdomain (only needed when student exists in multiple schools).

Returns: JSON object with student, class, grades, homework, exams, absences, messages

Inputs: school, since_days, student_name. Returns: result

get_subjectsA

Get all subjects taught at the school.

Args: school: School subdomain (only needed with multiple schools).

Returns: JSON array of lean subject records

Inputs: school. Returns: result

get_teachersA

Get all teachers in the school.

Args: school: School subdomain (only needed with multiple schools).

Returns: JSON array of lean teacher records

Inputs: school. Returns: result

get_timelineA

Get the visible timeline (recent messages, assignments, grades). System events (H_* types) are hidden by default.

Args: status: Filter by status — "active" (default), "done", or "all". starred: Filter by starred — "yes", "no", or "" (all). event_type: Raw type filter (comma-separated, e.g. "sprava,znamka"). category: Human-friendly category. One of: homework, grades, exams, messages, absences, events, news. Mutually exclusive with event_type. date_from: Start date (YYYY-MM-DD) for date range filter. date_to: End date (YYYY-MM-DD) for date range filter. limit: Max items to return (default 50). offset: Items to skip for pagination. include_system: Include system events like H_* types (default false). school: School subdomain (only needed with multiple schools).

Returns: JSON array of lean timeline events

Inputs: limit, offset, school, status, +6 more. Returns: result

get_timetableA

Get the timetable for a given date (defaults to today).

Args: date_str: Date in YYYY-MM-DD format. Leave empty for today. class_name: Class name (e.g. '6e', '4a'). If empty, uses logged-in user's timetable. student_name: Student name to look up their class timetable (e.g. 'Jan Novak'). Resolves the student's class automatically (searches all schools). school: School subdomain (only needed with multiple schools and no student_name).

Returns: JSON array of lean timetable lessons

Inputs: school, date_str, class_name, student_name. Returns: result

get_timetable_changesA

Get timetable changes / substitutions for a date (defaults to today).

Args: date_str: Date in YYYY-MM-DD format. Leave empty for today. school: School subdomain (only needed with multiple schools).

Returns: JSON array of timetable changes

Inputs: school, date_str. Returns: result

get_upcoming_eventsA

Get upcoming events and exams within the next N days.

Args: days_ahead: How many days ahead to look (default 30) school: School subdomain (only needed with multiple schools).

Returns: JSON array of upcoming events sorted by date (nearest first)

Inputs: school, days_ahead. Returns: result

loginA

Log in to Edupage using environment variables. No parameters needed if EDUPAGE_USERNAME, EDUPAGE_PASSWORD, and EDUPAGE_SUBDOMAIN are set. Supports multiple schools via comma-separated subdomains.

Args: username: Your Edupage username (defaults to EDUPAGE_USERNAME env var) password: Your Edupage password (defaults to EDUPAGE_PASSWORD env var) subdomain: Your school's Edupage subdomain, or comma-separated list for multi-school (defaults to EDUPAGE_SUBDOMAIN env var)

Returns: Success or error message

Inputs: password, username, subdomain. Returns: result

login_autoA

Log in to Edupage via the portal (auto-detect school). No parameters needed if EDUPAGE_USERNAME and EDUPAGE_PASSWORD are set.

Args: username: Your Edupage username / email (defaults to EDUPAGE_USERNAME env var) password: Your Edupage password (defaults to EDUPAGE_PASSWORD env var)

Returns: Success or error message

Inputs: password, username. Returns: result

rate_mealA

Rate a school meal (quality + quantity, each 1-5). ⚠️ Writes a real rating into EduPage for the logged-in boarder/child.

Args: quality: Food quality score 1-5 (required) quantity: Portion quantity score 1-5 (required) date_str: Date in YYYY-MM-DD format. Leave empty for today. meal_type: snack / lunch / afternoon_snack (or 1/2/3). Default lunch. menu_number: Optional choosable menu id (1=A, 2=B, …). Empty = ordered/first menu. school: School subdomain (only needed with multiple schools).

Returns: JSON with ok=true, submitted scores, and refreshed rating averages

Inputs: quality (required), quantity (required), school, date_str, +2 more. Returns: result

send_messageA

Send a message to one or more Edupage users. ⚠️ Use with care – this sends real messages.

Args: recipients: Comma-separated list of recipient names (must match teacher/student names exactly) body: The message text to send school: School subdomain (required when recipient exists in multiple schools).

Returns: Success or error message

Inputs: body (required), recipients (required), school. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 26 tools

    Disambiguation3/5

    Most tools are resource-specific, but several retrieval tools overlap: get_timeline, get_notifications, and get_notification_history share nearly identical filters and return similar event-like objects, while get_homework is a subset of get_assignments. The descriptions are detailed enough to disambiguate with careful reading, but an agent could easily misselect between timeline and notification tools.

    Naming Consistency5/5

    The get_<resource> pattern dominates and is applied uniformly across timetable, grades, students, teachers, classes, homework, meals, absences, and more. Non-get tools are clear, distinct actions (login, login_auto, rate_meal, send_message), with no mixed casing or inconsistent verb styles.

    Tool Count2/5

    26 tools exceeds the reasonable ceiling and feels heavy for what is mostly one school-information API. Several overlapping query surfaces (timeline vs notifications vs notification_history; homework vs assignments) inflate the count and could be consolidated. A trimmed set of roughly 15-18 tools would be more appropriate.

    Completeness4/5

    The set covers most of Edupage's domains: timetable, timetable changes, grades, homework/assignments, absences, events, meals, news, messages, students/teachers/classes, subjects, periods, plus authentication and write actions. Minor gaps exist, such as no direct inbox message tool, no way to mark homework/notifications done, and no logout, but agents can answer most school-related queries without hitting dead ends.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      Enables natural language queries about grades, GPA, attendance, and schedules by connecting Claude to StudentVue school dashboards. Includes analytical tools for grade simulation, what-if scenarios, and academic performance tracking based on live school data.
      19
      -
    • A
      license
      A
      quality
      F
      maintenance
      Enables Claude to access the ParentSquare school-parent communication platform via its web interface and internal APIs, covering parent features like feeds, calendars, messages, forms, and payments, plus school admin roster management such as students, guardians, classes, and staff.
      48
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Lets 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