Ida-Untis

Ein MCP-Server (Model Context Protocol), der WebUntis-Stundenplandaten für Claude bereitstellt: ausgefallene Stunden, Vertretungen, Raum-/Lehrerwechsel, Klassen, Lehrer, Räume, Fächer und Ferien. Läuft als Docker-Container und wird über einen bestehenden Cloudflare Tunnel unter einer eigenen Domain erreichbar gemacht.

Architektur

Claude  --https-->  Cloudflare Tunnel (öffentliche Domain)
                            |
                            v
                 127.0.0.1:8000 auf deinem Server
                            |
                            v
                 Docker-Container "ida-untis-mcp"
                            |
                            v
                      WebUntis JSON-API

Der Container published seinen Port nur auf 127.0.0.1 -- er ist von außen nicht direkt erreichbar, sondern nur über den bereits auf dem Server laufenden cloudflared-Prozess. Zusätzlich verlangt der Server bei jeder Anfrage ein geheimes Token (MCP_AUTH_TOKEN). Beides zusammen sorgt dafür, dass nicht "jeder" an die Domain kommt, selbst wenn die Domain bekannt ist.

Voraussetzungen

• Docker + Docker Compose auf dem Server

• Ein bereits eingerichteter und verbundener Cloudflare Tunnel auf diesem Server

• Ein WebUntis-Zugang (Schüler-, Eltern- oder Lehrer-Login)

• Ein GitHub-Repo namens Ida-Untis (dieses hier) mit Actions aktiviert

1. Einrichten

git clone https://github.com/<dein-user>/Ida-Untis.git
cd Ida-Untis
cp .env.example .env

.env ausfüllen:

.env bleibt lokal auf dem Server und wird nicht committet (steht in .gitignore).

2. Image bauen lassen (GitHub Actions)

Bei jedem Push auf main baut .github/workflows/docker-publish.yml das Docker-Image automatisch und veröffentlicht es nach ghcr.io/<dein-user>/ida-untis:latest.

Damit docker compose das Image ohne Login ziehen kann, muss das Package beim ersten Mal auf öffentlich gestellt werden: GitHub -> dein Profil -> Packages -> ida-untis -> Package settings -> Change visibility -> Public.

Alternativ (wenn privat bleiben soll): auf dem Server einmalig docker login ghcr.io -u <dein-user> mit einem Personal Access Token (Scope read:packages) ausführen.

3. Starten

docker compose pull
docker compose up -d
docker compose logs -f

Der Healthcheck prüft http://127.0.0.1:8000/healthz. Mit docker compose ps sollte der Container als healthy erscheinen.

4. An den bestehenden Cloudflare Tunnel anbinden

Kein neuer Tunnel nötig -- nur eine zusätzliche Ingress-Regel im bestehenden Tunnel, die auf den lokalen Port zeigt.

Dashboard (Zero Trust -> Networks -> Tunnels -> dein Tunnel -> Public Hostname):

• Hostname: z.B. untis.deine-domain.de

• Service: http://localhost:8000

Oder per config.yml, falls du den Tunnel so verwaltest:

ingress:
  - hostname: untis.deine-domain.de
    service: http://localhost:8000
  - service: http_status:404

Danach cloudflared neu laden bzw. den Tunnel-Dienst neu starten, damit die neue Ingress-Regel greift.

Optional für eine zusätzliche Sicherheitsebene: Die Hostname per Cloudflare Access (Zero Trust) zusätzlich auf bestimmte E-Mail-Adressen oder ein Service-Token einschränken -- dann muss man sowohl an Cloudflare Access als auch am MCP_AUTH_TOKEN vorbei.

5. Mit Claude verbinden

Der MCP-Endpunkt liegt unter https://untis.deine-domain.de/mcp (Streamable HTTP). Das Token kann auf drei Arten mitgeschickt werden -- je nachdem, was der jeweilige Claude-Client unterstützt:

• Header Authorization: Bearer <MCP_AUTH_TOKEN>

• Header X-API-Key: <MCP_AUTH_TOKEN>

• Query-Parameter ?token=<MCP_AUTH_TOKEN> (falls der Client nur eine reine URL akzeptiert, z.B. manche Custom-Connector-UIs)

Claude Code CLI:

claude mcp add --transport http ida-untis \
  https://untis.deine-domain.de/mcp \
  --header "Authorization: Bearer <MCP_AUTH_TOKEN>"

claude.ai / Claude Desktop (Custom Connector): Einstellungen -> Connectors -> Add custom connector -> URL eintragen. Falls dort kein Header konfigurierbar ist, die Token-Variante als Query-Parameter verwenden: https://untis.deine-domain.de/mcp?token=<MCP_AUTH_TOKEN>.

Verfügbare Tools

stundenplan, ausfaelle, aenderungen und vertretungen sind fest auf die in UNTIS_KLASSE konfigurierte Klasse eingestellt -- es gibt keinen Parameter, um eine andere Klasse abzufragen. Das ist bewusst so (Scope-Lock auf eine Klasse) und umgeht nebenbei auch ein WebUntis-Problem: manche Accounts haben für die generische "eigener Stundenplan"-Abfrage keine Berechtigung (Fehler no right for timetable), der Klassen-Stundenplan funktioniert aber unabhängig davon.

Datumsangaben immer als JJJJ-MM-TT, z.B. 2026-07-21.

Lokal testen ohne Cloudflare

docker compose up -d
curl -H "Authorization: Bearer $MCP_AUTH_TOKEN" http://127.0.0.1:8000/healthz

Troubleshooting

• Container startet nicht / beendet sofort: docker compose logs prüfen -- meist fehlt eine Pflicht-Variable in .env (klare Fehlermeldung beim Start).

• Login bei WebUntis schlägt fehl: UNTIS_SERVER/UNTIS_SCHOOL prüfen (Server nur als Host, ohne https://), Zugangsdaten in WebUntis selbst testen.

• Claude bekommt 401: Token in der Client-Konfiguration und in .env vergleichen (Groß-/Kleinschreibung, keine Leerzeichen).

• GHCR-Image lässt sich nicht pullen: Package-Sichtbarkeit prüfen (siehe Schritt 2) oder docker login ghcr.io auf dem Server ausführen.