Librus MCP Server
An MCP server that gives AI assistants access to Librus Synergia school data for one or more configured logins.
List login aliases and fetch student profile information such as class, tutor, school, register number and lucky number.
Retrieve grades: current, final, point, descriptive, formative/observation-card, and date-window grades.
Check attendance: records, details, totals by semester/year, and per-subject frequency.
View timetable, announcements, calendar events and details, homework and details, completed lessons, school-year archive, and class-free days.
Work with messages: list summaries, read message content, inspect attachments, look up recipient groups/recipients/correspondents/teacher subjects, and get unread counts.
Poll and acknowledge new-content notifications, and download message attachments to the server.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Librus MCP Server show me my daughter's recent grades and any absences this month"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Librus MCP Server
An MCP server that gives AI assistants access
to the Librus Synergia school gradebook: grades, attendance, timetable,
homework, calendar, announcements, messages, formative assessments, school-year
history, class-free days and student information. It supports
several logins at once, built on the independent
librus-python-api.
Version 2.0 replaces the librus-apix backend used by every earlier version.
Upgrading from 1.x? See Upgrading from 1.x.
Quick start
The commands below pin 2.8.1, using the native API 1.10.1. You need your Librus Synergia login and password. Accounts that require interactive two-factor authentication are not supported.
Pick one way to run it:
Way | Best for | Credentials |
Claude Code, Claude Desktop, Gemini CLI, Codex, OpenCode, Hermes on the same machine | a private | |
one-click install in apps that support MCP Bundles | the app's settings form, one login | |
agents on another machine of yours, connecting over HTTP | a private | |
clients that install servers from the official registry | the client's settings form, one login |
All of them run the server on a machine you control. It connects only to Librus; see Privacy.
On your computer
You do not need to clone this repository or install Python yourself. uv downloads Python 3.14 and the server automatically.
1. Install uv. On macOS or Linux, open a terminal and run:
curl -LsSf https://astral.sh/uv/install.sh | shOn Windows, open PowerShell and run:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"Close and reopen your AI assistant afterwards.
2. Create a private configuration file. Save this as config.json in a
private folder under your user account, outside projects and synchronized
folders, and fill in the login and password:
{
"accounts": [
{"alias": "daughter", "username": "12345", "password": "YOUR_PASSWORD"}
]
}The alias is the short name you use when asking about this login. For more
logins, add more objects to accounts, each with its own alias:
{
"accounts": [
{"alias": "anna", "username": "12345", "password": "FIRST_PASSWORD"},
{"alias": "jan", "username": "67890", "password": "SECOND_PASSWORD"}
]
}Suggested locations:
macOS:
/Users/YOUR_NAME/.config/librus-mcp/config.jsonLinux:
/home/YOUR_NAME/.config/librus-mcp/config.jsonWindows:
C:\Users\YOUR_NAME\.config\librus-mcp\config.json
On first start the server restricts the file to your user (macOS/Linux),
creates its private state directory (~/.librus-mcp) and a persistent key there.
There is nothing else to set up. Notifications and attachment downloads are on
by default; sending messages is off; opening a received message marks it read
without asking. To change that, add for example:
"features": {"notifications": true, "attachments": false, "send_message": true, "mark_read_consent": true}For a single login you can skip the file and set environment variables instead:
LIBRUS_USERNAME, LIBRUS_PASSWORD and optionally LIBRUS_ALIAS (default
librus). Installers that collect settings in a form use these.
3. Connect your assistant. Replace the path with your file's absolute path.
Claude Code:
claude mcp add --scope user --transport stdio librus \
-- uvx --python 3.14 librus-mcp==2.8.1 --config /absolute/path/to/config.jsonClaude Desktop (Settings > Developer > Edit Config):
{
"mcpServers": {
"librus": {
"command": "uvx",
"args": ["--python", "3.14", "librus-mcp==2.8.1", "--config", "/absolute/path/to/config.json"]
}
}
}Gemini CLI:
gemini mcp add --scope user --transport stdio \
librus uvx --python 3.14 librus-mcp==2.8.1 --config /absolute/path/to/config.jsonOpenAI Codex CLI:
codex mcp add librus \
-- uvx --python 3.14 librus-mcp==2.8.1 --config /absolute/path/to/config.jsonOpenCode:
opencode mcp add librus --global -- \
uvx --python 3.14 librus-mcp==2.8.1 --config /absolute/path/to/config.jsonHermes Agent (~/.hermes/config.yaml):
mcp_servers:
librus:
command: "uvx"
args: ["--python", "3.14", "librus-mcp==2.8.1", "--config", "/absolute/path/to/config.json"]Check the setup without contacting Librus:
uvx --python 3.14 librus-mcp==2.8.1 --config /absolute/path/to/config.json --check-configIf a GUI assistant cannot find uvx, use its absolute path (which uvx or
where uvx). Restart or reconnect the assistant after changing the file.
Desktop bundle (preview)
Each release attaches librus-mcp-2.8.1.mcpb to its
GitHub release. Open it
with an app that supports MCP Bundles, such as Claude Desktop. The app asks for
the Librus login and password, keeps them in its settings, and installs Python
3.14 and the exact dependency versions this release was tested with. The bundle
serves one login; use On your computer for several.
Self-hosted with Docker
Run the server on your own Docker host and connect agents on other machines over HTTP. Every request needs a bearer token. The server has no TLS of its own, so expose it only through a reverse proxy with TLS or a private network such as Tailscale or WireGuard. Never publish the port on a public or shared network.
1. Prepare a private folder on the Docker host with the configuration and a token. The files must belong to the user that runs the container and be readable only by it:
mkdir -p ~/librus-mcp/data && cd ~/librus-mcp
# config.json: the same format as above, any number of logins
docker run --rm ghcr.io/krzysztofbury/librus-mcp:2.8.1 --generate-token > token
chmod 600 config.json token2. Start it with this compose.yaml, replacing 1000:1000 with the output
of id -u and id -g:
services:
librus-mcp:
image: ghcr.io/krzysztofbury/librus-mcp:2.8.1
command: ["--transport", "http", "--allowed-host", "librus-mcp.example.lan:*"]
user: "1000:1000"
environment:
LIBRUS_CONFIG: /config/config.json
LIBRUS_MCP_TOKEN_FILE: /config/token
volumes:
- ./config.json:/config/config.json:ro
- ./token:/config/token:ro
- ./data:/data
ports:
# Loopback for a reverse proxy on this host, or your VPN address instead.
- "127.0.0.1:8000:8000"
restart: unless-stoppeddocker compose up -d
docker compose logs librus-mcpThe endpoint is /mcp at your proxy's HTTPS address, or at your VPN address on
port 8000. --allowed-host lists the host names clients use; NAME:* accepts
NAME with any port or none. A reverse proxy must forward the original Host
header: Caddy and Traefik do by default, nginx needs
proxy_set_header Host $host;. Without --allowed-host the server logs that
Host header checks are off and relies on the token alone. In the image the
server listens on every container interface; the ports: line decides who can
reach it. ./data keeps the private state, persistent key and downloads, so
back it up.
3. Connect your agent with the token as a bearer header. For Hermes Agent:
mcp_servers:
librus:
url: "https://librus-mcp.example.lan/mcp"
headers:
Authorization: "Bearer YOUR_TOKEN"Other clients that support streamable HTTP take the same URL and header.
Things to know about HTTP mode:
One token grants every configured login. Run one deployment per trusted person, and replace the token if it leaks.
Let one agent poll notifications for each login: delivery and acknowledgement are designed for a single consumer.
download_attachmentsaves files on the Docker host under./data/downloads. A remote agent cannot read that path; small files (up to 256 KiB) are also offered as a short-lived MCP resource.If you enable
send_message, anyone with the token can confirm a send preview. The server warns about this at startup.Without a
user:line the container runs as uid 10001; a named volume then works as is, but the configuration and token files must belong to uid 10001.Instead of files,
LIBRUS_ACCOUNTS(a JSON list of accounts), orLIBRUS_USERNAMEandLIBRUS_PASSWORDfor one login, andLIBRUS_MCP_TOKENcan be passed as environment variables.
The same image also runs over stdio for a client on the Docker host:
docker run -i --rm -v librus-mcp-data:/data -e LIBRUS_USERNAME -e LIBRUS_PASSWORD ghcr.io/krzysztofbury/librus-mcp:2.8.1.
MCP Registry
The server is listed in the official
MCP Registry as
io.github.krzysztofbury/librus-mcp, with the PyPI package, the container image
and the desktop bundle. Clients that install from the registry ask for
LIBRUS_USERNAME and LIBRUS_PASSWORD, and optionally LIBRUS_ALIAS.
Related MCP server: ecole-directe-mcp
Upgrading from 1.x
Change the version in your assistant's configuration to librus-mcp==2.8.1, add
--python 3.14 before it and keep your existing --config file. On first start
2.0 adapts the old setup automatically: it creates the key, restricts shared
1.x folders to your user, ignores the removed behaviour-notes setting and adopts
1.x notification history on the first check. Stop 1.x server processes that use
the same folders before switching, and copy the state folder first: going back
to 1.x is not supported other than by restoring that copy (see the
migration guide).
Notifications and attachments stay on by default, as in 1.x. Tool names and
results changed on purpose (for example list_students is now list_accounts
and student_alias is account_alias). Assistants read the new tool list
automatically; custom scripts must follow the migration guide.
Tools and safety
The default catalog has 32 typed tools:
Accounts/profile:
list_accounts,get_student_information.Grades:
get_grades,get_final_grades,get_grades_window.Attendance:
get_attendance,get_attendance_window,get_attendance_detail,get_attendance_frequency,get_subject_frequency.School:
get_timetable,get_announcements,get_agenda,get_agenda_detail,get_homework,get_homework_detail,get_completed_lessons,get_school_year_archive,get_class_free_days,get_justifications(parent logins).Communication:
get_messages,get_message_content,get_recipient_types,get_recipient_choices,get_recipients,get_message_correspondents,get_teacher_subjects,get_message_unread_counts.Notifications:
get_new_notifications,get_notification_status,acknowledge_notifications(featurenotifications).Files:
download_attachmentand runtime-only attachment resources (featureattachments).
Enabling the send_message feature adds preview_message, send_message,
get_send_outcome and get_send_history, for 36 tools. Disabling notifications
and attachments leaves 28 tools.
Collections are paged with limit and a cursor; an announcements page also
ends early when long texts would exceed the result size cap (reason: "size_limit"). Every login is independent,
including logins for the same student. Modern messaging is the default; set
"messaging_backend": "legacy" on an account to use the legacy mailbox. Behaviour
notes remain unavailable. Observation cards are supported as formative grades.
Point and percentage grades ("Oceny punktowe") are point records whose raw
value is a score on the scale named by their category.
Each grade has grade_id, its own Librus ID, stable across reads (2.7).
With scope all, a corrected grade and its correction are linked:
corrects on the correction and corrected_by on the original list the other
grade's grade_id, as Librus shows them in one bracket ([1 5]). Other
scopes show no brackets, so both fields are null there. See
grade IDs and corrections.
At schools that grade behaviour with points, get_grades and
get_grades_window list them in behaviour_points, apart from the grades:
per semester, the number the Zachowanie row shows (tally, not
interpreted) and its point entries. See
behaviour points.
On a parent login, get_justifications lists the absence justifications sent
through e-usprawiedliwienia with their status (sent, justified or rejected) and
who decided it. It covers only the window Librus shows by default, about the
last month, and changes no filter. A student login gets
UNSUPPORTED_CAPABILITY. See
e-Justifications.
What's new in 2.1
Keep your existing 2.0 configuration, context key and durable state; reconnect your assistant to refresh its tool catalog. The server pins API 1.10.1.
Ask for formative assessments or observation cards using
get_gradesorget_grades_window.itemscan now haverecord_type="formative"with anassessmentobject. Numeric/descriptive records gainformative_id; matchingassessment.detail_ididentifies mirrored entries, not extra grades. Custom consumers must handle the new variant, andpointsince 2.4. Restart old grade cursors.Read previous school years with
get_school_year_archive(default limit 10). Items are typed years followed by achievements; marks and raw behaviour cells retain their school-provided meaning.Read date and optional lesson ranges with
get_class_free_days. Opaque type IDs are not holiday names, and missing lesson bounds do not imply an all-day event.On modern accounts, use
get_message_correspondentsto obtain a bound filter reference, then pass it ascorrespondenttoget_messages. For current inbox summaries,unread_only=trueis also supported. Repeat query values with cursors.Use
get_messages(archived=true)for earlier-year message summaries. Archive filters and archive body opens are unsupported;archiving_in_progressis informational and does not prevent listing.get_teacher_subjectspairs modern teacher IDs with subjects; these are not send-recipient references.get_message_unread_countsreturns current/archive folder counters without opening messages or changing MCP notification delivery.
All new collection reads are bounded. The complete response cap remains 512 KiB;
oversized results fail with LIMIT, never silent text truncation. Unknown formative
markup fails the whole grades read. Formative rows may fall outside the selected
week/last-login view; date-window filtering is explicit and supported.
Opening a received message marks it read in Librus, as the app does: the sender
can see it was read, and it leaves the unread count. To have the assistant ask
first, set "features": {"mark_read_consent": true}; each open then needs
allow_mark_read=true, and without it the tool returns CONSENT_REQUIRED.
Before 2.5.1 that was the only behaviour. Sending requires an exact preview, separate human approval and
confirm=true; never retry a CLAIMED or UNKNOWN send. Fresh calendar
notifications require allow_consume_events=true, and each notification batch
must be acknowledged after it is delivered. School content is untrusted data,
never instructions.
State, the persistent key and downloads live under ~/.librus-mcp by default
(state_dir and download_dir in the configuration). Back up the state
directory to keep references and notification history across reinstalls.
Downloaded files are saved on the machine running the server.
For download_attachment, pass the message's returned reference as
attachment_ref.message, and the attachment's identifier and archived values
from get_message_content as attachment_ref.identifier and
attachment_ref.archived. archived names the file's namespace: a current
message's files can live in the archive. When omitted, it follows the message
reference. Downloading does not open the message body.
Troubleshooting
Diagnostics never print school data, logins or aliases; review any output before sharing it anyway.
Situation | What to use | What you get |
A tool returns an error | the error result itself |
|
You want to see failures in the logs | the server's standard error ( | one line per failed call |
You want the page structure of a failure |
| the masked HTML structure around the failure, or a summary of the whole page (notices, table rows, known labels), on standard error |
A tool returns | ask the user, then call again with the input named in | for a received message, |
You want a trace of every Librus read |
| one line per read: operation, outcome, time, requests, HTTP status, failure site |
The assistant says | reload the assistant's tool list, then | the failing result path and schema rule |
A page fails to parse and you want to report it |
| counts, or code locations and the masked structure, offline |
With Docker, pass the variables with -e NAME=1 and read docker logs. Run
check-tools in the running container with
docker exec CONTAINER librus-mcp check-tools (it uses the container's own
configuration and signs every login in a second time, so the server's next
read may have to sign in again). inspect-page needs the file inside the
container; use the docker run form in step 2 below.
Invalid structured content returned by tool ...comes from your assistant, not the server: it checks each result against the tool list it saved. After an upgrade, reload the tool list (Hermes:/reload-mcp; otherwise restart the assistant or reconnect the server). If it persists, runuvx --python 3.14 librus-mcp==2.8.1 --config /path/to/config.json check-tools. It calls every read tool that needs no reference for every login (about 20 tool calls per login, each one or more normal Librus reads, which change the views, week and month Librus remembers as the tools do), checks each result the way assistants do and prints the failing path and schema rule, never school data. Modern-only tools are skipped on legacy logins. Tools that need a reference or have an effect are never called: the detail tools,get_message_content,get_recipient_choices,get_recipients,download_attachment,get_new_notifications,acknowledge_notifications,preview_message,send_messageandget_send_outcome. Repeat--tool NAMEto check only those tools; the ones above are refused.A tool returns
PARSEorUNSUPPORTED_CAPABILITY: the error listswhereit failed and theversions. Your school's page has a layout the library does not read yet. To report it without sharing school data:In the browser, open the failing page and save its source as
page.html(UTF-8):Tool
Page
inspect-pageparserget_grades,get_grades_windowhttps://synergia.librus.pl/przegladaj_oceny/uczengradesget_final_gradesthe same page
final-gradesget_student_informationhttps://synergia.librus.pl/informacjaprofileOn Windows and Linux press Ctrl+U, then Ctrl+S. On macOS, in Safari use File > Save As with format Page Source; in Chrome press Option+Cmd+U, then Cmd+S. Do not paste the source into TextEdit: that saves a text document, which
inspect-pagerejects. A copied table (Inspect, Copy outer HTML) also works, but shows the page after its scripts ran.Run
uvx --python 3.14 librus-mcp==2.8.1 inspect-page grades page.html(with the parser from the table). With Docker:docker run --rm --user "$(id -u):$(id -g)" -v "$PWD:/in:ro" ghcr.io/krzysztofbury/librus-mcp:2.8.1 inspect-page grades /in/page.html(add:zafterroon SELinux hosts).Review the output and attach it to an issue, together with the
whereandversionsfrom the error.
If your saved page passes
inspect-pagebut the tool still fails, the server received a different page than your browser (a notice, an error page, or another login). Restart the server withLIBRUS_MCP_DIAGNOSE_FAILURES=1andLIBRUS_MCP_LOG_OPERATIONS=1, repeat the call, and attach the server's standard error: it summarizes the page the server received (notices, tables, known labels, lengths) and the response size, without its text.
Privacy
The server runs on a machine you control, your computer or your own Docker host, and connects only to Librus. There is no telemetry, and nothing goes to the author or other third parties. Tool results go to the AI assistant that asked for them. See PRIVACY.md.
Development
uv sync --locked
uv run pytest -q
uv run ruff check src/librus_mcp tests_native release_verification scripts
uv run ruff format --check src/librus_mcp tests_native release_verification scripts
uv run mypy
uv run bandit -r src/librus_mcp -c pyproject.toml -qSee MIGRATION_2_0.md for configuration precedence and operator commands, MCP_CONTRACT.md for protocol rules, NATIVE_TEST_PLAN.md for verification evidence and SPEC.md for ownership.
License and limitations
2.x is MIT licensed. LICENSE_REVIEW.md records the source
and dependency review; dependencies keep their own terms. Unshipped 1.x
references in legacy_reference/ remain GPL-3.0-only, and earlier releases keep
their original licenses.
This is an unofficial integration, not affiliated with Librus. Upstream changes can break supported features. Report security issues privately as described in SECURITY.md.
Available Tools
32 toolsacknowledge_notificationsAcknowledge notificationsADestructive
Confirm that a batch from get_new_notifications reached the user, so it is not returned again. Call only after delivery; this cannot be undone.
Inputs: context (required), receipt (required), account_alias (required). Returns: context, receipt, acknowledged
download_attachmentDownload attachmentA
Save one message attachment to the server's private download folder and return its local path, size and SHA-256. Never overwrites a file or opens the message. On Linux and macOS, files up to 256 KiB are may also be offered as a 15-minute MCP resource.
Inputs: filename (required), account_alias (required), attachment_ref (required), max_bytes. Returns: sha256, filename, local_path, size_bytes, +3 more
get_agendaCalendarA
List one month of school calendar events such as tests, trips and days off. Pass an event's reference, when present, to get_agenda_detail. Selecting the month also changes the month this login's Librus session remembers.
Inputs: year (required), month (required), account_alias (required). Returns: year, items, month, identity, +3 more
get_agenda_detailCalendar event detailsARead-only
Get every detail of one calendar event. Use the same account_alias that get_agenda used.
Inputs: event_ref (required), account_alias (required). Returns: data, identity, observation
get_announcementsAnnouncementsARead-only
List school announcements with their full text, in the order Librus shows them. A page ends at limit or earlier when the texts are long; pass pagination.next_cursor for the rest. Each page rereads the announcements. Does not mark them read in Librus.
Inputs: account_alias (required), limit, cursor. Returns: items, identity, pagination, observation
get_attendanceAttendanceA
List attendance records. For a date range use get_attendance_window; for totals use get_attendance_frequency. scope also changes the view this login's Librus session remembers.
Inputs: account_alias (required), limit, scope, cursor. Returns: items, scope, identity, semesters, +2 more
get_attendance_detailAttendance detailsARead-only
Get every field Librus shows for one attendance record, such as date and topic. The id comes from get_attendance, get_attendance_window or get_completed_lessons.
Inputs: account_alias (required), attendance_id (required). Returns: data, identity, observation
get_attendance_frequencyAttendance frequencyARead-only
Get attendance totals for each semester and the year: attended, total, excluded and unknown lessons, with ratios from 0 to 1 (null when undefined). For a per-subject breakdown use get_subject_frequency.
Inputs: account_alias (required). Returns: data, identity, observation
get_attendance_windowAttendance by dateA
List attendance records dated within date_from..date_to. Use this instead of get_attendance for a date range. scope also changes the view this login's Librus session remembers.
Inputs: account_alias (required), limit, scope, cursor, +2 more. Returns: items, scope, date_to, identity, +3 more
get_class_free_daysClass-free daysARead-only
List the class's days and lesson ranges without classes, such as holidays and school free days. type_id is an opaque code, not a name; a day without lesson numbers is not necessarily free all day.
Inputs: account_alias (required), limit, cursor. Returns: items, identity, pagination, observation
get_completed_lessonsCompleted lessonsA
List lessons already held between two dates: subject, teacher, topic and attendance mark. Continue with the returned cursor and the same dates. The range also changes what this login's Librus session remembers.
Inputs: date_to (required), date_from (required), account_alias (required), limit, +2 more. Returns: items, date_to, identity, date_from, +2 more
get_final_gradesFinal gradesARead-only
Get midterm, predicted and annual grades per subject as the school published them. A column the school does not show is unavailable; an empty or - raw value is not given yet. For individual grades use get_grades or get_grades_window.
Inputs: account_alias (required). Returns: items, identity, pagination, observation
get_gradesGradesA
List grades with averages: numeric, point, descriptive and formative assessments, including observation cards. A point grade's raw is a score on the scale its category names, such as (0-100); point_results are period results on that scale, never averages. For a date range use get_grades_window. scope also changes the view this login's Librus session remembers and may not apply to formative rows. A grade whose formative_id equals a formative row's assessment.detail_id is one assessment, not two. grade_id is the grade's own Librus ID, not a formative detail_id. With scope all, corrects lists the grade_ids a correction replaces and corrected_by the later corrections of a grade; other scopes show no correction brackets and leave both null. behaviour_points are the Zachowanie row's points per semester, not grades.
Inputs: account_alias (required), limit, scope, cursor. Returns: items, scope, averages, identity, +5 more
get_grades_windowGrades by dateA
List grades and formative assessments dated within date_from..date_to, without averages (see get_grades). A point grade's raw is a score on the scale its category names. scope also changes the view this login's Librus session remembers and may not apply to formative rows. A grade whose formative_id equals a formative row's assessment.detail_id is one assessment. grade_id, corrects and corrected_by: see get_grades. behaviour_points: only entries dated in the range.
Inputs: account_alias (required), limit, scope, cursor, +2 more. Returns: items, scope, date_to, identity, +4 more
get_homeworkHomeworkA
List homework in a date range; give both dates or neither (today to 14 days ahead, Warsaw time). Pass an item's reference to get_homework_detail. The range also changes what this login's Librus session remembers.
Inputs: account_alias (required), date_to, date_from. Returns: items, date_to, identity, date_from, +2 more
get_homework_detailHomework detailsARead-only
Get the full text of one homework assignment. Does not mark it read in Librus.
Inputs: homework_ref (required), account_alias (required). Returns: data, identity, observation
get_justificationsAbsence justificationsARead-only
List absence justifications parents sent via e-usprawiedliwienia, in Librus's order, with status sent, justified or rejected and decided_by. Covers only date_from..date_to, the window Librus shows by default; older entries are omitted. Parent logins only; a student login returns UNSUPPORTED_CAPABILITY. Changes no filter Librus remembers; each page rereads the list.
Inputs: account_alias (required), limit, cursor. Returns: items, date_to, identity, date_from, +2 more
get_message_contentRead messageADestructive
Get a message's full text and attachments. Opening a received message marks it read in Librus, as the app does. A server can require consent for that: on CONSENT_REQUIRED, ask the user, then call again with allow_mark_read=true. Archived messages cannot be opened.
Inputs: message_ref (required), account_alias (required), allow_mark_read. Returns: data, backend, context
get_message_correspondentsMessage correspondentsARead-only
Modern accounts: list the people in a mailbox folder, to filter get_messages by correspondent. These references cannot address a new message; use get_recipients for that.
Inputs: account_alias (required), limit, cursor, folder. Returns: items, identity, pagination, observation
get_messagesMessagesA
List message summaries (correspondent, subject, date, read state) without opening them; use get_message_content for the text. On legacy accounts the folder choice changes the view Librus remembers. Modern accounts can list the archive or filter current mail by correspondent or unread_only; archives cannot be filtered. Repeat the same filters with cursor.
Inputs: account_alias (required), limit, cursor, folder, +5 more. Returns: items, folder, backend, archived, +6 more
get_message_unread_countsUnread message countsARead-only
Modern accounts: get unread message counts for the current and archive folders without opening messages. Independent of get_new_notifications.
Inputs: account_alias (required). Returns: data
get_new_notificationsNew notificationsADestructive
Check a login for new grades, attendance, messages, announcements, calendar events or homework. The batch is stored and returned again, for the same categories, until acknowledge_notifications. Librus reports new calendar events only once, so they need allow_consume_events=true. Changes the grade, attendance and homework views Librus remembers; never opens messages.
Inputs: categories (required), account_alias (required), allow_consume_events. Returns: data, delivery_semantics, acknowledgement_required
get_notification_statusNotification statusARead-only
Show whether a login has an unacknowledged notification batch or an uncertain delivery to resolve. Offline: it does not check Librus or acknowledge anything.
Inputs: account_alias (required). Returns: data, has_pending_work
get_recipient_choicesRecipient choicesA
Legacy accounts only: list the sub-choices of a hierarchical recipient group, such as classes. Put the chosen item's reference.selection_id into recipient_type for get_recipients. Changes this login's Librus form state. Modern accounts return UNSUPPORTED_CAPABILITY.
Inputs: account_alias (required), recipient_type (required). Returns: items, backend, context, identity, +2 more
get_recipientsRecipientsA
List the people in one recipient group, to address a message. Modern students and parents groups include virtual accounts only with include_virtual=true in recipient_type. On legacy accounts the lookup changes this login's Librus form state. Nothing is sent.
Inputs: account_alias (required), recipient_type (required). Returns: items, backend, context, identity, +2 more
get_recipient_typesRecipient typesA
List the recipient groups this login can message and whether each can be looked up. Pass a group's reference to get_recipients, or on legacy accounts to get_recipient_choices. On legacy accounts the lookup changes this login's Librus form state. Sends nothing.
Inputs: account_alias (required). Returns: items, backend, identity, pagination, +1 more
get_school_year_archiveSchool year archiveARead-only
List earlier school years with their marks and behaviour, then achievements. Cells keep Librus's exact text; a year's year_end mark may differ from that year's annual grade. Each page rereads the archive.
Inputs: account_alias (required), limit, cursor. Returns: items, identity, pagination, observation
get_student_informationStudent informationARead-only
Get the profile of the student a login represents: name, class, register number, tutor, school and lucky number. Each login is an independent parent or student account.
Inputs: account_alias (required). Returns: data, observation
get_subject_frequencyAttendance by subjectARead-only
Get attendance counts and ratios per subject, optionally within a window of up to 371 days. For overall totals use get_attendance_frequency.
Inputs: account_alias (required), date_to, date_from. Returns: items, date_to, identity, date_from, +2 more
get_teacher_subjectsTeacher subjectsARead-only
Modern accounts: list teachers with the subjects they teach. The IDs are informational and cannot address a message; use get_recipients for that.
Inputs: account_alias (required), limit, cursor. Returns: items, identity, pagination, observation
get_timetableTimetableA
Get the lesson plan for one week, with substitutions and cancellations, in school local time. Selecting the week also changes the week this login's Librus session remembers.
Inputs: monday (required), account_alias (required). Returns: items, monday, identity, timezone, +2 more
list_accountsList accountsARead-only
List the configured login aliases. Call this first: every other tool takes one as account_alias. Offline.
Inputs: no named parameters. Returns: items
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 32 tools
Most tools target a clearly distinct resource+action, and descriptions explicitly route callers between near-pairs (get_attendance vs get_attendance_window vs get_attendance_frequency vs get_subject_frequency). Residual confusion remains in the recipient cluster (get_recipient_types, get_recipient_choices, get_recipients, get_message_correspondents), where legacy-vs-modern and lookup-vs-addressing distinctions are subtle.
Names are uniformly snake_case with a predictable verb_noun shape (get_grades, get_homework_detail, acknowledge_notifications, download_attachment). The only deviation is list_accounts against an otherwise get_-dominated read convention, which is minor and still readable.
32 tools is heavy for a single school-journal integration; a substantial share is generated by parallel _window variants (grades, attendance), _detail variants and legacy/modern duplicates in the messaging cluster. The domain is genuinely broad, so it is defensible, but the surface is over-partitioned rather than minimally scoped.
Read coverage is excellent across grades, attendance, timetable, homework, announcements, agenda, archive and notifications. However, the messaging path is a dead end: three tools (get_recipient_types, get_recipient_choices, get_recipients) exist solely 'to address a message' yet no send_message tool is offered, and there is no way to file a justification, only to list them.
Maintenance
Related MCP Connectors
Let AI agents use any website you're logged in to. Sessions stay encrypted on your machine.
Web search, data extraction and controlled browser automation for AI assistants via OAuth.
LinkedIn for AI agents: inbox, invitations, Sales Navigator search, posts, jobs, quotas, webhooks.
Let AI agents use your real, signed-in Chrome: tabs, clicks, forms, screenshots and video.
Related MCP Servers
- FlicenseAqualityCmaintenanceEnables read-only access to a Librus Portal account, letting users list linked Synergia accounts and retrieve grades, attendance, timetable, homework, notices, and school information.3-
- FlicenseNot gradedqualityBmaintenanceConnects AI agents to the École Directe API to access grades, homework, timetables, school life, messages, and documents.-
- AlicenseAqualityBmaintenanceEnables AI agents to query and manage EduPage school accounts, including timetables, grades, homework, meals, messages, multi-school discovery, role-aware student switching, and 2FA login.31131 PyPI4MIT
- AlicenseAqualityCmaintenanceEnables AI assistants to access a child's WebUntis school data read-only, including timetables, homework, exams, absences, and schedule changes, with credentials kept locally.11MIT