lanis MCP server
Commit Nov 9, 2026Lets an AI client access Schulportal Hessen data including timetables, substitution plans, homework, and messages.
Also known as udondan/lanis
- Stars
- 2
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 9, 2026
- License
- MIT
What is lanis MCP?
lanis lets an AI client access Schulportal Hessen data including timetables, substitution plans, homework, and messages.
Summary generated from the project's README
About lanis MCP server
Accessing Schulportal Hessen data directly from an AI assistant is what lanis enables for students and teachers. By connecting this MCP server to clients like Claude Desktop, users can query their school information using natural language. The server provides read-only access to essential academic data, including substitution plans, timetables, homework assignments, calendar events, and messages.
To set up the connection, you must provide your school ID and credentials such as a username and password or a session cookie via environment variables. The server can be run locally using uvx or via a Docker container. It is designed to be a lightweight way to bridge the gap between the Lanis portal and intelligent agents, allowing for quick checks on upcoming tasks or schedule changes without manual login through a web browser.
What you can do with it
- 1Check daily schedule changesAsk the AI to retrieve the current substitution plan to see if any classes have changed.
- 2Track upcoming homeworkRequest a list of all homework assignments due within a specific timeframe.
- 3Review school calendar eventsQuery the assistant to display all scheduled appointments or events for a particular month.
- 4Monitor school communicationsCheck for any new or unread messages within the school portal.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
LANIS_PASSWORDLANIS_SCHOOL_IDLANIS_USERNAME
| Name | Description | |
|---|---|---|
| LANIS_PASSWORD | — | |
| LANIS_SCHOOL_ID | — | |
| LANIS_USERNAME | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableudondan/lanis is public and reachablegithub.com/udondan/lanis ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-09github.com/udondan/lanis ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHublanis
[!NOTE] Inoffizielles Community-Projekt. Nicht mit dem Land Hessen oder dem Schulportal Hessen verbunden, nicht von ihnen unterstützt oder autorisiert.
Zugriff auf das Schulportal Hessen (Lanis) aus Python, aus dem Terminal und aus KI-Assistenten: Vertretungsplan, Stundenplan, Kalender, Hausaufgaben, Nachrichten, Dateien und mehr.
lanis bietet drei gleichwertige Zugänge zu denselben Daten:
| Zugang | Für | Start |
|---|---|---|
| Python-SDK | eigene Programme und Automatisierungen | from pylanis import Lanis |
| Kommandozeile | das Terminal und Shell-Skripte (JSON-Ausgabe) | lanis <befehl> |
| MCP-Server | KI-Assistenten wie Claude | lanis mcp |
lanis liest nur. Es verändert keine Daten im Schulportal.
Installation
Das Paket pylanis braucht Python 3.11 oder neuer und wird auf PyPI veröffentlicht.
# Als Bibliothek in einem Projekt
pip install pylanis # oder: uv add pylanis
# Den Befehl lanis global installieren
uv tool install pylanis # oder: pipx install pylanis
# Ohne Installation ausprobieren
uvx --from pylanis lanis schools
Kommandozeile und MCP-Server gibt es auch als Docker-Image udondan/lanis (amd64 und arm64), ganz ohne Python:
docker run --rm udondan/lanis schools
Das Image führt den Befehl lanis aus. Ohne Argument startet es den MCP-Server.
Die Images sind mit cosign signiert. So prüfst du, dass ein Image vom Release-Workflow dieses Repositorys stammt:
cosign verify udondan/lanis:latest \
--certificate-identity-regexp '^https://github\.com/udondan/(py)?lanis/\.github/workflows/publish\.yml@refs/tags/v' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com
Anmeldung
Du brauchst einen Lanis-Account und die Schul-ID deiner Schule. Die Schul-ID findest du ohne Anmeldung:
uvx --from pylanis lanis --format markdown schools | grep -i "musterstadt"
Es gibt drei Arten, sich anzumelden. Das SDK nimmt die Zugangsdaten als Parameter, Kommandozeile und MCP-Server lesen sie aus Umgebungsvariablen (Lanis.from_env() im SDK ebenso).
| Art | Umgebungsvariablen | SDK-Parameter |
|---|---|---|
| Benutzername & Passwort (empfohlen) | LANIS_SCHOOL_ID, LANIS_USERNAME, LANIS_PASSWORD |
school_id, username, password |
| Schule nach Name & Stadt | LANIS_SCHOOL_NAME, LANIS_SCHOOL_CITY, LANIS_USERNAME, LANIS_PASSWORD |
school_name, school_city, username, password |
| Session-Cookie (kein Passwort) | LANIS_SCHOOL_ID, LANIS_SESSION_ID |
school_id, session_id |
Mit Benutzername und Passwort meldet sich lanis automatisch neu an, wenn die Session abläuft. Ein Session-Cookie läuft irgendwann ab und muss dann ersetzt werden.
Session speichern (optional): Mit LANIS_DATA_DIR (SDK: data_dir) wird die Session in session.json in diesem Verzeichnis gespeichert, sodass nach einem Neustart keine neue Anmeldung nötig ist. Die Datei ist nur für dich lesbar. Ohne diese Einstellung bleibt die Session nur im Speicher.
Verfügbare Daten
Alle drei Zugänge bieten dieselben Daten:
| Daten | SDK (Lanis) |
Kommandozeile (lanis) |
MCP-Tool |
|---|---|---|---|
| Schulen mit ID (ohne Anmeldung) | get_schools() |
schools |
get_schools |
| Vertretungsplan | get_substitution_plan() |
substitutions |
get_substitution_plan |
| Stundenplan | get_timetable() |
timetable |
get_timetable |
| Lerngruppen/Kurse | get_learning_groups() |
learning-groups |
get_learning_groups |
| Kalender für einen Zeitraum | get_calendar(start, end) |
calendar --start … --end … |
get_calendar |
| Kalender des aktuellen Monats | get_calendar_of_month() |
calendar |
get_calendar_of_month |
| Aufgaben aus „Mein Unterricht" | get_tasks() |
tasks |
get_tasks |
| Nachrichten | get_conversations(number=10) |
conversations [--number N] |
get_conversations |
| Dateispeicher | get_file_storage(folder_id=None) |
files [--folder ID] |
get_file_storage |
| Dateiverteilung | get_file_distribution() |
file-distribution |
get_file_distribution |
| Aktive Wahlen | get_votes() |
votes |
get_votes |
| App-Kacheln und Ordner im Dashboard | get_apps(), get_folders() |
apps, folders |
get_apps, get_folders |
| Unterstützte Apps der Schule | get_available_apps(), is_app_available() |
available-apps, check-app NAME |
get_available_apps, check_app_availability |
Hinweise:
- Mit
include_responsible=True(SDK),--responsible(Kommandozeile) bzw.include_responsible(MCP) enthalten Kalendertermine die verantwortliche Person. Dafür ist pro Termin eine zusätzliche Anfrage nötig, das kann bei vielen Terminen dauern. number=-1lädt alle Nachrichten und belastet den Lanis-Server stark. Bitte sparsam verwenden.
Python-SDK
from datetime import date
from pylanis import Lanis
lanis = Lanis(school_id="1234", username="vorname.nachname", password="dein-passwort")
# oder: Lanis.from_env() liest die LANIS_*-Umgebungsvariablen
for task in lanis.get_tasks():
print(task.subject_name, task.title, task.date)
plan = lanis.get_substitution_plan()
for sub in plan.substitutions:
print(sub.hours, sub.class_name, sub.subject, sub.substitute)
events = lanis.get_calendar(date(2026, 11, 1), date(2026, 11, 30))
- Die Methoden geben Dataclasses zurück (
Task,SubstitutionPlan,CalendarEvent,Timetableusw.), Datumswerte alsdate/datetime. - Die Anmeldung passiert beim ersten Aufruf, der sie braucht.
Lanis.get_schools()braucht keine. - Jede
Lanis-Instanz hat ihre eigene Session, mehrere Konten in einem Prozess sind möglich.
Fehler:
ConfigurationError: Die übergebenen Zugangsdaten sind unvollständig.SessionExpiredError: Die Session ist abgelaufen (nur bei Anmeldung per Session-Cookie) und wurde zurückgesetzt.
Abhängigkeiten: pylanis legt seine Abhängigkeiten auf exakte Versionen fest, damit Kommandozeile und MCP-Server nur mit getesteten Versionen laufen. Braucht dein Projekt eine andere Version, z. B. von httpx, kannst du die Vorgabe mit uv überschreiben:
# pyproject.toml deines Projekts
[tool.uv]
override-dependencies = ["httpx>=0.28"]
Kommandozeile
Der Befehl lanis gibt die Daten als JSON aus, mit --format markdown als lesbaren Text.
export LANIS_SCHOOL_ID=1234
export LANIS_USERNAME=vorname.nachname
export LANIS_PASSWORD=dein-passwort
lanis substitutions
lanis --format markdown tasks
lanis calendar --start 2026-11-01 --end 2026-11-30
lanis timetable | jq '.entries[] | select(.day == "Montag")'
Alle Befehle stehen in der Tabelle Verfügbare Daten. lanis --help und lanis <befehl> --help zeigen alle Optionen. Fehler werden als Error: … auf stderr ausgegeben, der Befehl endet dann mit Exit-Code 1.
Mit Docker
-e NAME ohne Wert übernimmt die Variable aus deiner Shell:
docker run --rm -e LANIS_SCHOOL_ID -e LANIS_USERNAME -e LANIS_PASSWORD udondan/lanis substitutions
Damit nicht jeder Aufruf eine neue Anmeldung braucht, speichert ein Volume die Session (siehe Anmeldung). Als Alias verhält sich das Image dann wie ein installiertes lanis:
alias lanis='docker run --rm -e LANIS_SCHOOL_ID -e LANIS_USERNAME -e LANIS_PASSWORD -e LANIS_DATA_DIR=/data -v lanis-data:/data udondan/lanis'
lanis --format markdown tasks
MCP-Server
lanis mcp startet einen MCP-Server über stdio. Damit kann ein KI-Assistent die Daten abfragen, und du fragst einfach:
- „Was steht heute im Vertretungsplan?"
- „Welche Hausaufgaben habe ich diese Woche?"
- „Zeig mir alle Termine im April."
- „Habe ich ungelesene Nachrichten?"
Claude Desktop
Öffne die Konfigurationsdatei von Claude Desktop:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
Füge einen Eintrag unter mcpServers hinzu. Die Umgebungsvariablen entsprechen der Tabelle unter Anmeldung:
{
"mcpServers": {
"lanis": {
"command": "uvx",
"args": ["--from", "pylanis", "lanis", "mcp"],
"env": {
"LANIS_SCHOOL_ID": "1234",
"LANIS_USERNAME": "vorname.nachname",
"LANIS_PASSWORD": "dein-passwort"
}
}
}
}
Nach dem Speichern Claude Desktop neu starten.
Mit Docker statt uvx sieht der Eintrag so aus. -e NAME ohne Wert reicht die Variable aus env an den Container weiter:
{
"mcpServers": {
"lanis": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e",
"LANIS_SCHOOL_ID",
"-e",
"LANIS_USERNAME",
"-e",
"LANIS_PASSWORD",
"udondan/lanis"
],
"env": {
"LANIS_SCHOOL_ID": "1234",
"LANIS_USERNAME": "vorname.nachname",
"LANIS_PASSWORD": "dein-passwort"
}
}
}
}
Docker MCP Toolkit
Mit dem Docker MCP Toolkit von Docker Desktop läuft der Server als Container hinter dem MCP Gateway. Der Gateway startet den Container bei Bedarf und reicht die Tools an die verbundenen Clients weiter. Die Zugangsdaten liegen dabei als Secrets in Docker Desktop statt im Klartext in der Client-Konfiguration.
Voraussetzung: Docker Desktop mit aktiviertem MCP Toolkit.
-
Die Server-Definition
docker-mcp.ymlherunterladen und zu einem Toolkit-Profil hinzufügen. Das Toolkit liest solche Dateien nur aus seinem Katalog-Verzeichnis:mkdir -p ~/.docker/mcp/catalogs curl -fsSL https://raw.githubusercontent.com/udondan/lanis/main/docker-mcp.yml -o ~/.docker/mcp/catalogs/lanis.yml # neues Profil "lanis" ... docker mcp profile create --name lanis --id lanis --server "file://$HOME/.docker/mcp/catalogs/lanis.yml" # ... oder zu einem bestehenden Profil hinzufügen docker mcp profile server add default --server "file://$HOME/.docker/mcp/catalogs/lanis.yml"Das Profil hält das Image auf dem Stand, den es beim Hinzufügen hatte. Für ein Update
profile server adderneut ausführen. -
Zugangsdaten als Secrets hinterlegen (siehe Anmeldung):
docker mcp secret set lanis.school_id=1234 docker mcp secret set lanis.username=vorname.nachname docker mcp secret set lanis.password=dein-passwort -
Einen Client mit dem Profil verbinden:
docker mcp client connect claude-desktop --profile lanisWeitere Clients wie
claude-code,cursorodervscodezeigtdocker mcp client connect --help. Alternativ geht das in Docker Desktop unter MCP Toolkit.
docker mcp gateway run --profile lanis --dry-run --verbose prüft die Einrichtung, ohne einen Client zu starten. Am Ende sollte lanis: (15 tools) stehen.
Ausgabe
Die meisten Tools haben einen Parameter response_format: markdown (Standard, für Menschen lesbar) oder json (maschinenlesbar). Du kannst das Format einfach in deiner Frage angeben, z. B. „Zeig mir den Vertretungsplan als JSON."
Antworten sind auf 25.000 Zeichen begrenzt. Längere Ergebnisse werden gekürzt und mit einem Hinweis versehen. Grenze die Abfrage dann ein, z. B. mit einem kürzeren Zeitraum im Kalender.
Fehlerbehebung
Session abgelaufen
Betrifft nur die Anmeldung per Session-Cookie, mit Benutzername und Passwort meldet sich lanis selbst neu an. Einen neuen Session-Cookie eintragen oder auf Benutzername und Passwort wechseln.
App an der Schule nicht verfügbar
Nicht alle Schulen haben alle Lanis-Module aktiviert. lanis available-apps (bzw. get_available_apps) zeigt, welche der unterstützten Apps freigeschaltet sind.
Kein Vertretungsplan
Den Vertretungsplan gibt es nur an Schultagen, nicht an Wochenenden und Feiertagen. Manche Schulen zeigen die App „Vertretungsplan" an, nutzen sie aber nicht. Dann meldet lanis, dass keine Vertretungsdaten vorliegen.
Keine Termine gefunden
Prüfe den Zeitraum. start und end müssen im Format JJJJ-MM-TT angegeben werden.
Verbindungsfehler
Prüfe die Zugangsdaten (beim MCP-Server die Umgebungsvariablen in der Client-Konfiguration bzw. die Secrets im Docker MCP Toolkit) und ob du Zugang zum Schulportal Hessen hast (ggf. VPN oder Schulnetzwerk erforderlich).
Lizenz
lanis steht unter der MIT-Lizenz.
Der Ordner src/pylanis/lanisapi/ basiert auf LanisAPI 0.4.1 von Dacjan Gapinski. Das Projekt wird nicht mehr weiterentwickelt; der Code wurde überarbeitet und wird hier gepflegt. LanisAPI steht ebenfalls unter der MIT-Lizenz, siehe src/pylanis/lanisapi/LICENSE.
Disclaimer
Dieses Projekt ist ein inoffizielles, unabhängiges Open-Source-Projekt und steht in keiner Verbindung zum Land Hessen oder zum Hessischen Ministerium für Kultus, Bildung und Chancen. Schulportal Hessen und LANIS sind Angebote des Landes Hessen. Die Namen werden ausschließlich zur Beschreibung der Kompatibilität verwendet. Die Nutzung erfolgt auf eigenes Risiko und unter Beachtung der Nutzungsbedingungen des Schulportals Hessen.
lanis MCP questions
Can the server modify data in Schulportal Hessen?
No, the server is read-only and does not change any data in the school portal.
How do I authenticate with the MCP server?
You can authenticate using a username and password, school name and city, or a session cookie via environment variables.
What kind of data can I access?
You can access substitution plans, timetables, learning groups, calendars, homework, messages, and files.