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.

Requirements

• Python 3.14 or newer
• MCP Python SDK 2.x (mcp>=2.1.1,<3), installed automatically as a dependency

Since v1.1.0 this server runs on the 2.x line of the MCP Python SDK. The 1.x entry point it was previously built on (FastMCP) was renamed to MCPServer upstream, so the two SDK majors are not interchangeable: v1.1.0 requires mcp 2.x, and v1.0.0 requires mcp 1.x.

This is not a change to the tool surface. Every tool, argument, and annotation is unchanged, so no configuration change is needed and uvx librus-mcp resolves the right SDK on its own. It only matters if you pin the MCP SDK yourself in a shared environment, where mcp<2 will no longer work. Hosts now also display this server's own version in the connection handshake rather than the SDK's.

Acknowledgments

This project is built on top of the excellent librus-apix library by RustySnek. Their work on reverse-engineering and maintaining a Python client for the Librus Synergia platform made this MCP server possible. If you find this project useful, please consider starring their repository as well.

Quick Start

1. Add to your AI assistant

Pick your client. Credentials are passed directly via the env block — no files or cloning needed.

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "librus": {
      "command": "uvx",
      "args": ["librus-mcp"],
      "env": {
        "LIBRUS_ACCOUNTS": "[{\"alias\":\"daughter\",\"username\":\"12345\",\"password\":\"...\"}]"
      }
    }
  }
}

Claude Code

Via the /mcp command or in ~/.claude.json (global):

{
  "mcpServers": {
    "librus": {
      "command": "uvx",
      "args": ["librus-mcp"],
      "env": {
        "LIBRUS_ACCOUNTS": "[{\"alias\":\"daughter\",\"username\":\"12345\",\"password\":\"...\"}]"
      }
    }
  }
}

Gemini CLI

Add to ~/.gemini/settings.json (global) or .gemini/settings.json (project-level):

{
  "mcpServers": {
    "librus": {
      "command": "uvx",
      "args": ["librus-mcp"],
      "env": {
        "LIBRUS_ACCOUNTS": "[{\"alias\":\"daughter\",\"username\":\"12345\",\"password\":\"...\"}]"
      }
    }
  }
}

OpenAI Codex CLI

Add to ~/.codex/config.toml (global) or .codex/config.toml (project-level):

[mcp_servers.librus]
command = "uvx"
args = ["librus-mcp"]

[mcp_servers.librus.env]
LIBRUS_ACCOUNTS = '[{"alias":"daughter","username":"12345","password":"..."}]'

Note: uvx automatically downloads and runs the package from PyPI — no cloning or virtual environments needed. You only need uv installed (curl -LsSf https://astral.sh/uv/install.sh | sh).

Providing credentials

Each account represents a parent's login to Librus Synergia for a specific child. In the Polish school system, parents receive separate Librus login credentials for each of their children. The alias is a friendly name you choose to identify which child's data you're accessing. The username and password are the parent portal credentials you use to log in at synergia.librus.pl.

Limitation: accounts that require interactive two-factor authentication are not supported — the underlying librus-apix library has no 2FA flow, so such accounts fail at login.

There are three ways to provide credentials (checked in this order):

Multiple children

Add multiple accounts to the JSON array:

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

Using a config file with uvx

If you prefer a file over inline JSON:

{
  "mcpServers": {
    "librus": {
      "command": "uvx",
      "args": ["librus-mcp"],
      "env": {
        "LIBRUS_CONFIG": "/Users/you/.config/librus/secrets.json"
      }
    }
  }
}

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 .
cp secrets.json.template secrets.json   # Then fill in credentials

Then use the full path in your MCP config:

{
  "mcpServers": {
    "librus": {
      "command": "/path/to/librus-mcp/.venv/bin/librus-mcp"
    }
  }
}

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.

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              # Configuration loader (reads secrets.json)
  notification_state.py  # Per-student persistence of seen-notification IDs
  scraping.py            # Own Synergia scraping: attachments, behaviour notes
tests/                   # pytest suite with mocked librus-apix

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

Security

To report vulnerabilities, see SECURITY.md.

License

This project is licensed under the MIT License. See LICENSE for details.