iServ MCP

Unofficial, standalone Model Context Protocol server for iServ school portals. It retrieves parent letters, their full text and attachments, and can explicitly mark letters as read. Timetable tools from the HAiServ client are included as well.

This project is not affiliated with or endorsed by IServ GmbH. iServ instances can differ; test against your school installation before relying on it.

MCP tools

A single attachment is limited to 25 MiB. Downloads are accepted only from the configured HTTPS origin and below /iserv/. Directories use mode 0700; files use 0600.

Related MCP server: librus-mcp

Install

Python 3.11 or newer is required.

git clone <repository-url> iserv-mcp
cd iserv-mcp
python -m venv .venv
.venv/bin/pip install .

For development and tests:

.venv/bin/pip install -e '.[test]'
.venv/bin/pytest

Credentials

Copy the included example to your private configuration directory:

mkdir -p ~/.config/iserv-mcp
cp credentials.example.json ~/.config/iserv-mcp/credentials.json
chmod 600 ~/.config/iserv-mcp/credentials.json

Then edit ~/.config/iserv-mcp/credentials.json:

{
  "url": "https://school.example/iserv/",
  "username": "your-username",
  "password": "your-password"
}

The launcher rejects credential files readable by group or others. Passwords, session cookies and response bodies are not intentionally logged. Never commit the credential file.

Run

After installation:

iserv-mcp

Or directly from a checkout:

.venv/bin/python -m iserv_mcp

Optional flags:

--credentials PATH   use another mode-0600 credential file
--download-dir PATH  choose where attachments are stored

The default download directory is ~/.local/share/iserv-mcp/attachments.

Hermes configuration

Hermes can launch the installed stdio server directly:

mcp_servers:
  iserv:
    command: "/absolute/path/to/iserv-mcp/.venv/bin/iserv-mcp"
    args: []
    timeout: 120
    connect_timeout: 30
    sampling:
      enabled: false

Restart Hermes after changing config.yaml. Tools are registered with names such as mcp_iserv_get_parentletters.

For multiple agents or hosts, install the package separately on each host and create a separate local credential file there. This avoids exposing the MCP server or credentials over the LAN. A shared HTTP deployment would need its own authentication and is therefore deliberately not the default.

Design notes

• Authentication uses a normal iServ web session and automatically renews an expired session for supported requests.

• Reading a letter does not automatically mark it as read.

• mark_parentletter_read is separated from read tools and requires an explicit confirmation argument.

• Attachments remain on the MCP host and are never uploaded automatically.

• Sick notes use the verified DieSchulApp guardian API. The server validates the selected child against the live guardian child list and defaults to preview-only.

Attribution and license

Parts of the iServ client and parsers are derived from HAiServ by jjoswig. See NOTICE. The project is licensed under the MIT License; see LICENSE.