Librus MCP Server

An MCP (Model Context Protocol) server that provides AI assistants with access to the Librus Synergia electronic gradebook. It supports multiple student accounts simultaneously and exposes tools for grades (numeric, GPA, and descriptive), messages, attendance, homework, schedules, timetables, announcements, completed lessons, and student information.

Quick Start

You do not need to clone this repository or install Python yourself. The setup uses uv, which installs the correct Python version and Librus MCP automatically.

You need your parent login and password for Librus Synergia. Accounts requiring interactive two-factor authentication are not supported by the underlying library.

1. Install uv

On macOS or Linux, open a terminal and run:

curl -LsSf https://astral.sh/uv/install.sh | sh

On Windows, open PowerShell and run:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Close and reopen your AI assistant after installing uv. You can verify the installation in a new terminal with uvx --version.

2. Create a private credentials file

Create a file named secrets.json in a private folder under your user account, outside projects and shared or synchronized folders:

{
  "accounts": [
    {
      "alias": "daughter",
      "username": "12345",
      "password": ""
    }
  ]
}

Replace the empty password value with your Librus password. The alias is the short name you will use when asking your assistant about this student. For more than one child, add another account object to the array.

Use the absolute path to this file in the next step. ~ is not expanded in LIBRUS_CONFIG. Example paths:

• macOS: /Users/YOUR_NAME/.config/librus-mcp/secrets.json
• Linux: /home/YOUR_NAME/.config/librus-mcp/secrets.json
• Windows JSON: C:\\Users\\YOUR_NAME\\AppData\\Roaming\\librus-mcp\\secrets.json

On macOS or Linux, protect the finished file so only your user can read it:

chmod 600 /absolute/path/to/secrets.json

3. Connect your AI assistant

Choose only the client you use. Replace /absolute/path/to/secrets.json with the path created above.

Claude Desktop

Open Settings > Developer > Edit Config and add this MCP server. The config file is normally at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows.

{
  "mcpServers": {
    "librus": {
      "command": "uvx",
      "args": ["librus-mcp==1.2.6"],
      "env": {
        "LIBRUS_CONFIG": "/absolute/path/to/secrets.json"
      }
    }
  }
}

Claude Code

Run this once in a terminal:

claude mcp add --scope user --transport stdio librus \
  -e LIBRUS_CONFIG=/absolute/path/to/secrets.json \
  -- uvx librus-mcp==1.2.6

Gemini CLI

Run this once in a terminal. User scope keeps school credentials out of project files.

gemini mcp add --scope user --transport stdio \
  -e LIBRUS_CONFIG=/absolute/path/to/secrets.json \
  librus uvx librus-mcp==1.2.6

OpenAI Codex CLI

Run this once in a terminal:

codex mcp add librus \
  --env LIBRUS_CONFIG=/absolute/path/to/secrets.json \
  -- uvx librus-mcp==1.2.6

Never put a Librus password or LIBRUS_ACCOUNTS in a project-level MCP configuration. Project files can be committed, synchronized, or shared.

4. Restart and verify

1. Completely restart Claude Desktop, or reconnect Librus in your CLI client.
2. Ask: "Use Librus to list the configured students."
3. Check that your chosen aliases appear.
4. Ask: "Use Librus to show grades for daughter." Replace daughter with your alias. This second request performs a real Librus login.

For CLI status checks, use claude mcp list, gemini mcp list, or codex mcp list. Claude Code and Gemini CLI also expose status through /mcp.

Troubleshooting

• uvx not found: run uvx --version in a new terminal, then completely restart the AI assistant. GUI applications may require the absolute path to uvx.
• Config file does not exist: use an absolute path, not ~. In JSON on Windows, write each backslash twice, for example C:\\Users\\....
• Credential file permissions are too open: on macOS or Linux, run chmod 600 /absolute/path/to/secrets.json. The server refuses files readable or writable by group or other users.
• Aliases appear but grades fail: verify the same parent credentials at synergia.librus.pl.
• Login requires a second factor: interactive 2FA accounts are not currently supported.

Configuration Reference

Credential sources are checked in this order and are not merged:

1. LIBRUS_ACCOUNTS, if set.
2. The absolute file path in LIBRUS_CONFIG, if set.
3. secrets.json in the server working directory.
4. secrets.json beside a source checkout.

Invalid higher-priority configuration produces an error instead of silently falling back. LIBRUS_FEATURES, LIBRUS_STATE_DIR, and LIBRUS_DOWNLOAD_DIR provide separate overrides for optional tools and local storage.

All LIBRUS_* environment variables, JSON-file values, defaults, and source priorities are declared and resolved in src/config.py with Pydantic Settings. The rest of the application receives one validated AppConfig snapshot and does not read configuration directly from the environment.

Account aliases must be 1 to 80 printable characters with no surrounding whitespace. Unknown account fields are rejected. Passwords are redacted from validation and startup errors.

For advanced environments, LIBRUS_ACCOUNTS accepts a JSON array directly:

[{"alias":"daughter","username":"12345","password":"..."}]

Alternative: Install from Source

If you prefer to run from a local clone:

git clone https://github.com/krzysztofbury/librus-mcp.git
cd librus-mcp
uv venv && uv pip install -e .

Point LIBRUS_CONFIG at the private credentials file created during Quick Start, then use the local executable in your MCP config:

{
  "mcpServers": {
    "librus": {
      "command": "/path/to/librus-mcp/.venv/bin/librus-mcp",
      "env": {
        "LIBRUS_CONFIG": "/absolute/path/to/secrets.json"
      }
    }
  }
}

Contributors can run the credentialed source-tree smoke test with uv run python verify_connection.py --all-accounts.

Available Tools

All tools carry MCP ToolAnnotations (read-only / destructive / idempotent hints), so MCP hosts can apply their own safety policies.

Optional tools (feature gates)

These tools are registered based on the features section of the configuration (or the LIBRUS_FEATURES env var, a JSON object merged over it):

send_message uses a two-step confirmation: the first call sends nothing and returns a preview plus a single-use confirm_token (valid 5 minutes); only a second call with that token delivers the message. Titles are limited to 200 characters, content to 15,000 characters, and a call to 50 unique numeric recipient IDs. The combined UTF-8 payload is limited to 64 KiB.

Librus exposes recently added schedule events only once. Librus MCP checkpoints each complete result locally as one atomic batch before continuing. After that checkpoint succeeds, a cancelled call or failed state update can replay the event instead of losing it. Recovery uses at-least-once delivery, so a replayed schedule event may appear again. A connection failure, parse failure, local storage failure, or machine crash before the atomic checkpoint completes can still lose data from this read-once upstream view. Calls process at most 500 schedule events; a larger consumed result remains in the bounded spool and drains across later calls before another read-once schedule request is made.

Non-attachment Librus responses are streamed with a 4 MiB body limit, including chunked responses and the cumulative bodies in a redirect chain. Attachment downloads use their separate 50 MiB streaming cap.

Attachment downloads cooperate with caller cancellation and operation timeouts. Cancellation actively closes a blocked response stream and is serialized against the final atomic publication step, so a download cannot publish later after cancellation wins that commit boundary. Available bytes are processed without waiting for a 64 KiB buffer to fill, so the absolute download deadline also applies to slow-drip responses. Requests require identity content encoding and reject encoded bodies that could buffer outside this bounded download loop.

Behaviour notes default off because only the empty page has been verified against live Synergia markup. Operators may opt in with behaviour_notes: true; malformed or incomplete note layouts fail explicitly instead of returning partial records.

Example with all options:

{
  "accounts": [{"alias": "daughter", "username": "12345", "password": "..."}],
  "features": {
    "notifications": true,
    "attachments": true,
    "behaviour_notes": true,
    "send_message": false
  },
  "state_dir": "~/.librus-mcp/state",
  "download_dir": "~/.librus-mcp/downloads"
}

Attachment files are streamed to an exclusive temporary file and published atomically without overwriting existing files. The download directory must be on a filesystem that supports hard links.

Project Structure

src/
  server.py              # MCP server with tool definitions and entry point
  librus_client.py       # Librus API client wrapper with caching and retry
  config.py               # All operator settings, defaults, and source precedence
  notification_state.py   # Seen IDs and read-once schedule recovery spool
  scraping.py            # Own Synergia scraping: attachments, behaviour notes
tests/                   # pytest suite with mocked librus-apix

Acknowledgments

This project is built on the excellent librus-apix library by RustySnek. Its reverse-engineered Librus client makes this MCP server possible.

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

Security

To report vulnerabilities, see SECURITY.md.

License

Copyright (C) 2026 Krzysztof Bury.

This project is licensed under the GNU General Public License v3.0 only (GPL-3.0-only). See LICENSE for the complete terms.

The project adopted GPL-3.0-only in v1.2.2 to honor the strongest license terms actually distributed with its required librus-apix==1.5.1 dependency. That dependency declares MIT in package metadata, but both its source repository and the LICENSE files bundled in its PyPI wheel and source archive contain the complete GPL-3.0 text. Using GPL-3.0-only avoids relying on the contradictory metadata when redistributing this combined application.