Omnivox MCP

Ein MCP-Server, der die Studentenportale der Quebecer Colleges (Omnivox/Lea) über MCP-Tools und ein REST-Tool-Gateway verfügbar macht.

Es führt einen persistenten Puppeteer-Browser aus, der bei Omnivox angemeldet ist, und führt Anfragen über das eigene JavaScript der Website aus – so werden Challenge-Response-Authentifizierung, Cookies und Kodierung nativ gehandhabt.

Funktionen

• 30 MCP-Tools – Kurse, Noten, Stundenplan, Kalender, Nachrichten (MIO), Dokumente, Aufgaben, Neuigkeiten vom College

• Zwei Transportmodi – HTTP (Standard, Express-Server mit MCP über HTTP + REST-Tool-Gateway) oder stdio (veraltet, nicht empfohlen)

• REST-Tool-Gateway – alle MCP-Tools werden als einfache HTTP-Endpunkte für Nicht-MCP-Agenten bereitgestellt

• Dateidownloads – direkte Binärdateien oder temporäre browserfreundliche Links (15 Min. TTL)

• Interne Nachrichten – MIO-Nachrichten lesen, suchen, senden, markieren, verschieben und löschen

• Permanente Sitzung – Das Chrome-Profil übersteht Neustarts, kein erneutes Anmelden erforderlich

Related MCP server: Canvas MCP Server

Schnellstart

# 1. Clone and install
git clone https://github.com/Beat-YT/omnivox-mcp.git
cd omnivox-mcp
npm install

# 2. Authenticate (first time only)
cd omnivox-connection
npm install && npm start
# Log in through the Electron window, save the data files

# 3. Start the server
cd ..
npm start              # HTTP mode (default) — Express server on port 3000
npm run start:stdio    # stdio mode (deprecated, not recommended)

HTTP-Modus (Standard): Startet einen Express-Server mit MCP über HTTP unter /mcp?key=... und ein REST-Tool-Gateway. Der Zugriffsschlüssel wird automatisch unter ~/.omnivox/accessKey.txt generiert.

Stdio-Modus (veraltet, nicht empfohlen): Der MCP-Client startet den Server als Unterprozess und kommuniziert über stdin/stdout. Kein Express-Server und kein Zugriffsschlüssel erforderlich.

Jede Instanz bedient ein Omnivox-Konto. Der Server verwaltet eine einzelne Browsersitzung, die mit dem Konto verbunden ist, mit dem Sie sich angemeldet haben.

Erneute Authentifizierung

Wenn Ihre Sitzung abläuft oder Sie sich bei einem anderen Konto anmelden müssen, setzen Sie die Sitzungsdaten zurück und führen Sie die Electron-App erneut aus:

npm run reset
cd omnivox-connection && npm start
# Log in, wait for the success dialog, then close the window
cd .. && npm start

npm run reset löscht ~/.omnivox/browser/, cookies.json und config.json, sodass der Server beim nächsten Start neu beginnt.

Konfiguration

Legen Sie diese als Umgebungsvariablen oder in einer .env-Datei im Projektstamm fest:

Verwendung

MCP (für KI-Assistenten)

Stdio-Modus (veraltet, nicht empfohlen): Fügen Sie den Server zu Ihrer MCP-Client-Konfiguration hinzu – er startet den Server als Unterprozess. Verwenden Sie npm run start:stdio. Siehe AGENT_SETUP.md für die Verbindungskonfiguration.

HTTP-Modus: Verbinden Sie Ihren MCP-Client über den Streamable-HTTP-Transport mit http://localhost:3000/mcp?key=YOUR_KEY.

In beiden Fällen erhält die KI Zugriff auf alle 30 Tools – fragen Sie sie in natürlicher Sprache nach Ihren Noten, Ihrem Stundenplan, Ihren Aufgaben oder Nachrichten.

REST-Tool-Gateway (HTTP-Modus)

Für Agenten oder Apps, die MCP nicht unterstützen, werden alle Tools als einfache HTTP-Endpunkte bereitgestellt:

# List all available tools
curl http://localhost:3000/tools -H "x-mcp-auth: YOUR_KEY"

# Get your courses
curl -X POST http://localhost:3000/tools/get-courses-summary \
  -H "x-mcp-auth: YOUR_KEY" -d '{}'

# Check your grades
curl -X POST http://localhost:3000/tools/get-grades-summary \
  -H "x-mcp-auth: YOUR_KEY" -d '{}'

# Read your inbox
curl -X POST http://localhost:3000/tools/get-mio-messages \
  -H "x-mcp-auth: YOUR_KEY" -d '{}'

Der Tools-Endpunkt akzeptiert JSON-Bodies unabhängig vom Content-Type-Header – ein explizites Setzen ist nicht erforderlich.

Omnivox-Proxy (HTTP-Modus)

Der Server stellt einen Durchgangsproxy unter /Mobl/* bereit, der Anfragen über die authentifizierte Browsersitzung direkt an die mobile Omnivox-API weiterleitet. Jede HTTP-Methode und jeder Inhaltstyp wird unterstützt.

# Example: hit an Omnivox mobile API endpoint directly
curl http://localhost:3000/Mobl/some/endpoint \
  -H "x-mcp-auth: YOUR_KEY" -H "Content-Type: application/json" -d '{}'

Dies ist nützlich, wenn Sie einen Omnivox-Endpunkt aufrufen müssen, der nicht von einem MCP-Tool umschlossen ist.

Eigene Projekte erstellen

Das REST-Tool-Gateway ist nicht nur für KI – es ist eine vollständige Omnivox-API, die Sie in jedem Projekt verwenden können:

• Noten-Dashboard – ziehen Sie Ihre Noten in eine eigene Web-App oder Tabelle

• Stundenplan-Widget – zeigen Sie Ihren Wochenplan auf einem Startbildschirm oder Desktop-Widget an

• Aufgaben-Tracker – erstellen Sie Benachrichtigungen für neue Aufgaben oder bevorstehende Fristen

• Discord/Slack-Bot – lassen Sie sich benachrichtigen, wenn neue Noten oder Nachrichten eingehen

• Mobile App – erstellen Sie einen eigenen Omnivox-Client mit genau den Funktionen, die Sie benötigen

• Datenexport – archivieren Sie Ihre Noten, Dokumente und Nachrichten für Ihre eigenen Aufzeichnungen

Jede Sprache, die HTTP-Anfragen senden kann, funktioniert – Python, JavaScript, Swift, Kotlin, Go, was auch immer Sie bevorzugen. Verwenden Sie GET /tools, um alle verfügbaren Tools und ihre Eingabeschemata zu entdecken.

Dokumentation

Siehe Wiki für die vollständige Dokumentation:

• Einrichtung – Voraussetzungen, Installation, Umgebungsvariablen

• Architektur – wie das System aufgebaut ist

• MCP-Tools – alle 30 Tools mit Parametern

• REST-Tool-Gateway – Verwendung des Tool-Gateways für Nicht-MCP-Agenten

• Authentifizierung – Zugriffsschlüssel, Web-Token, Sitzungsverwaltung

Ist das sicher?

Wir sehen nie Ihr Passwort oder Ihre Daten. Alles läuft lokal auf Ihrem Computer (oder Ihrem eigenen Server):

• Sie melden sich selbst an über die Electron-App – Ihr Omnivox-Passwort wird direkt auf der offiziellen Omnivox-Anmeldeseite eingegeben. Dieses Projekt fragt Ihr Passwort nie ab, speichert es nicht und überträgt es nicht.

• Keine externen Server. Der MCP-Server läuft vollständig auf Ihrem Rechner. Ihre Daten durchlaufen nie einen Drittanbieterdienst – alle Anfragen gehen direkt zwischen Ihrem Server und Omnivox.

• Sitzung bleibt lokal. Die Browsersitzung und Cookies werden in ~/.omnivox/ auf Ihrer Festplatte gespeichert. Nur Sie haben Zugriff darauf.

• Open Source. Der gesamte Quellcode steht Ihnen hier zur Prüfung zur Verfügung. Es gibt keine versteckten Netzwerkaufrufe, Analysen oder Telemetrie.

Bewährte Sicherheitspraktiken

• Setzen Sie den Server niemals ohne HTTPS ein. Verwenden Sie einen Reverse-Proxy (z. B. Nginx) mit TLS. Siehe Setup-Wiki für eine Beispielkonfiguration.

• Halten Sie ~/.omnivox/ privat. Es enthält Ihre Omnivox-Sitzung und Ihren Zugriffsschlüssel. Behandeln Sie accessKey.txt wie ein Passwort – teilen Sie es mit niemandem.

• Siehe Sicherheitsvorkehrungen für weitere Details.

Haftungsausschluss

Dieses Projekt ist inoffiziell und weder mit Skytech Communications, Omnivox oder einem Quebec-College verbunden, noch von diesen unterstützt oder assoziiert. Es wird nur für den persönlichen und Bildungsgebrauch bereitgestellt, ohne jegliche Gewährleistung. Die Nutzung erfolgt auf eigenes Risiko – die Autoren sind nicht verantwortlich für Konsequenzen, die sich aus der Nutzung ergeben, einschließlich, aber nicht beschränkt auf Kontoeinschränkungen, Datenverlust oder Verstöße gegen die Nutzungsbedingungen Ihrer Einrichtung.

Lizenz

ISC