Skip to main content
Glama

Omnivox MCP

A self-hosted toolbox that logs into Omnivox once and lets anything talk to it — Claude over MCP, any assistant that can call plain HTTP tools, or your own scripts.

Under the hood it runs a persistent Puppeteer browser logged into your Omnivox session, executing requests through the mobile app's own JavaScript (without any scraping) — so challenge-response auth, cookies, and encoding are all handled natively.

Core Features

  • An MCP server: 34 tools covering all of LEA, MIO messaging, schedule, calendar, documents, assignments, and college news.

  • An OpenAPI tools gateway: every MCP tool doubled as a plain HTTP endpoint, with a live catalog and a full OpenAPI 3.1 spec at GET /openapi.json. Virtually any assistant or agent framework that supports JSON-described tools can use it.

  • A raw Omnivox proxy: /Mobl/* passes any request straight through the authenticated session, for direct access to JSON data from the Mobile API directly.

  • A research effort: the mobile API this all sits on is undocumented, so we document it ourselves as we reverse-engineer it. The growing field notes live in docs/.

Everything runs on your machine (or your server, or a container). One instance = one Omnivox account.

Quick start

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

# 2. Authenticate on a desktop with UI (first time only)
cd omnivox-connection
npm install && npm start
# Log in through the Electron window, save cookies.json + config.json,
# then place them in a folder named data/ at the project root (or your OMNIVOX_DATA_DIR)

# 3. Start the server
cd ..
npm start              # Express server on port 3000

The server starts with MCP-over-HTTP at /mcp?key=..., the REST tool gateway, and the proxy. An access key is auto-generated at data/accessKey.txt — that's your password to the whole thing, treat it accordingly.

(There's also a stdio mode, npm run start:stdio, where an MCP client launches the server as a subprocess — deprecated and not recommended.)

Docker

Prefer containers? Authenticate once with the Electron app, then copy the example compose file and set your data folder path:

cp docker-compose.example.yml docker-compose.yml
# Edit docker-compose.yml — replace /path/to/config/folder with your data folder
docker compose up -d

The included docker-compose.example.yml mounts your data folder into the container at /data/omnivox, exposes port 3000, sets a session-keeping refresh interval, and wires up a healthcheck. Your customized docker-compose.yml is gitignored.

Re-authentication

If your session expires or you want a different account, reset and log in again:

npm run reset
cd omnivox-connection && npm start
# Log in, save the two files, place them back in your data folder
cd .. && npm start

npm run reset clears browser/, cookies.json, config.json, and accessKey.txt from the data folder so the server starts fresh.

Configuration

Set these as environment variables or in a .env file at the project root:

Variable

Default

Description

PORT

3000

Server port

OMNIVOX_DATA_DIR

data/ at the project root

Data directory for config, cookies, browser profile, and access key

OMNIVOX_CONFIG / OMNIVOX_COOKIES

(none)

Contents of config.json / cookies.json (JSON or base64), for hosts where a volume isn't an option. Only used when the file is missing.

BROWSER_LAUNCH_ARGS

(none)

Extra Chrome flags appended to the default launch arguments, space-separated. Useful in Docker where Chrome runs as root and needs --no-sandbox --disable-setuid-sandbox.

BROWSER_SLEEP

false

When true, the browser closes after 5 minutes of inactivity and relaunches on the next request. Saves memory at the cost of a cold-start delay. Not recommended for Docker setups

BROWSER_REFRESH_INTERVAL

(disabled)

Interval in minutes between automatic page refreshes to keep the Omnivox session alive. Recommended for long-lived instances (e.g. 10). Disabled when BROWSER_SLEEP is true.

MCP_SERVER_URL

(none)

Optional. Public base URL that enables download link generation (get-document-link / get-assignment-file-link). Set to your public domain (e.g. https://omnivox.example.com).

ENABLE_EXTERNAL_SERVICE_LINKS

false

When true or 1, enables get-service-link tool which hands pre-authenticated links to web-only Omnivox services (lockers, advisor appointments, progression chart, ...). These link logs into the full web portal, which is why it is off by default. Enable at your own risk. With MCP_SERVER_URL set the tool returns a short link; otherwise it returns the raw single-use URL.

DISABLE_LOGGER

3000

Disables server.log file writing in data folder

Related MCP server: unofficial-magister-mcp

Using it

With an MCP assistant

Connect your MCP client to http://localhost:3000/mcp?key=YOUR_KEY via Streamable HTTP transport. That's it — the assistant gets all 34 tools and you can ask about grades, schedules, assignments, or messages in natural language.

With any other assistant (REST tool gateway)

No MCP? No problem. Every tool is a plain HTTP endpoint, and the catalog is self-documenting two ways: GET /tools returns names, descriptions, and JSON Schema inputs, while GET /openapi.json serves a full OpenAPI 3.1 spec — import it into anything that speaks OpenAPI (custom GPT actions, Open WebUI, LangChain toolkits, ...). Feed either to your assistant, POST its tool calls through, done.

# List all available tools (with their input schemas)
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 '{}'

The tools endpoint accepts JSON bodies regardless of Content-Type — no need to set it explicitly.

Straight to Omnivox (the proxy)

For anything the tools don't cover, /Mobl/* forwards requests directly to Omnivox's mobile API through the authenticated browser — any method, any content type, session cookies included:

curl -X POST http://localhost:3000/Mobl/LeaEtudiant/GetNotesDetailModel \
  -H "x-mcp-auth: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"AnSession":"20261","noCours":"2434K6EM","noGroupe":"1011"}'

Pair it with the endpoint notes in docs/ and you have the whole mobile API at your fingertips.

In your own projects

The gateway isn't just for AI — it's a full Omnivox API for anything that speaks HTTP:

  • Grade dashboard — pull your grades into a web app or spreadsheet

  • Schedule widget — your timetable on a home screen or desktop widget

  • Assignment tracker — notifications for new assignments and deadlines

  • Discord/Slack bot — get pinged when grades or messages land

  • Mobile app — a custom Omnivox client with just the features you care about

  • Data export — archive your grades, documents, and messages

Python, JavaScript, Swift, Kotlin, Go — whatever you like. Start from our docs.

The research corner

Omnivox's mobile API has no public documentation, so this repo doubles as a field guide. docs/ collects what we've mapped so far:

  • Per-module endpoint docs — request bodies and response shapes for every /Mobl/ controller we've charted, from LÉA grades to MIO messaging.

  • The service manifest — how GetOffreService describes the modules the app is assembled from, what the flags actually mean, and how its change-detection hash is built.

  • The native bridge — how the mobile pages talk to the host app through ComNatifOvx.js: per-platform transports, the command/callback convention, and why it stays backward compatible with old app versions.

  • The web handoff: how a portal-only module in the manifest turns into the pre-authenticated URL the app opens in a native window, layer by layer.

  • Conventions — the ×100 fixed-point grade encoding, int-sentinel "no value" markers, term ID format, the common response envelope.

Some of it was found by reading the app's bundle, some by probing live endpoints — including a few natively-served endpoints the official app doesn't even use anymore (that's how per-evaluation grades work here without HTML scraping). If you chart new territory, contributions are warmly welcome.

Will this break?

The usual worry, on reading that this fakes the native app's JavaScript bridge: surely the next Omnivox update kills it. It doesn't, and not by luck. The mobile pages are served fresh from Omnivox on every load, but the native app only changes when a user installs a store update, so Skytech's own JS has to keep working against every app build still installed anywhere. It is written to assume nothing about the bridge: unknown commands are swallowed, unanswered callbacks are tolerated, and anything new is gated behind the app version the user agent declares. We pin that version, so the page never asks for something the emulated bridge doesn't know.

What can drift is the ordinary stuff: a /Mobl/ response shape (fixed in a transformer, like any API client) and a session that eventually expires (log in again). The bridge is the least likely thing here to need attention. The mechanics, with the exact gates, are in the native bridge notes.

Documentation

The Wiki is the operator's manual:

  • Setup — prerequisites, installation, first login, Docker, VPS deployment, security precautions

  • Connecting Assistants — MCP client configs, and non-MCP assistants via the tool catalog / OpenAPI spec

  • Troubleshooting — common issues and fixes

For the API surface itself, the server is self-documenting: GET /tools and GET /openapi.json always reflect the running instance, and the Omnivox mobile API notes live in docs/.

Security

The short version: this behaves like a browser you left logged in on your own computer — nothing more, nothing less. The longer version, because it matters:

Your password and 2FA are untouched

  • You log in yourself, on the real login page. The Electron app opens the official Omnivox login — password, 2-Step Verification, trusted-device prompt and all. This project never asks for, sees, stores, or replays your password or MFA codes.

  • MFA keeps working. Omnivox's 2-Step Verification is fully compatible: you complete it once during login, and the resulting session (including the trusted-device cookie) is stored exactly as any browser would store it. Nothing here bypasses, weakens, or automates any Omnivox security mechanism — requests run through Omnivox's own JavaScript, so challenge-response auth and session expiry work exactly as Skytech designed them.

  • Keep MFA enabled. This project works fine with it, and you should absolutely leave it on.

What's stored, and where

  • Session cookies and browser profile — the data folder on your disk (data/ in the project, gitignored), same as a logged-in browser. Nothing is sent anywhere else.

  • Access key — data/accessKey.txt, auto-generated, protects every endpoint the server exposes.

  • No external servers, no telemetry. Everything runs on your machine or your server; all traffic goes directly between you and Omnivox. The codebase is open — audit it.

What the access key can do

Treat accessKey.txt like your Omnivox password. Anyone holding it gets your full session: reading grades and messages, sending MIO, downloading documents. If it ever leaks:

  1. Delete accessKey.txt (a new key is generated on restart), and

  2. npm run reset + re-login if you want to invalidate the session itself.

Hardening checklist

  • Don't expose the server to the internet unless you actually need to. Localhost or LAN is the happy default. If you must go public: TLS via a reverse proxy (e.g. Nginx — sample config), and consider IP allowlisting.

  • In Docker, bind to loopback unless you're fronting it with a proxy: "127.0.0.1:3000:3000" instead of "3000:3000".

  • Keep the data folder private — it's gitignored already; add file permissions, and disk encryption if it's a laptop.

  • One instance, one account, by design — there is nothing multi-tenant to leak across.

  • More in Security Precautions.

A note for Skytech

This is a personal-use client for a student's own account — functionally a browser with an API, authenticating through your own login flow, MFA included, one account per instance. It doesn't harvest credentials, doesn't circumvent any protection, and can't see anything the logged-in student can't already see in the portal themselves. If you're from Skytech or a college and have concerns, please open an issue — happy to talk.

Disclaimer

This project is unofficial and not affiliated with, endorsed by, or associated with Skytech Communications, Omnivox, or any Quebec college. It is provided as-is for personal and educational use only. Use it at your own risk — the authors are not responsible for any consequences resulting from its use, including but not limited to account restrictions, data loss, or violations of your institution's terms of service.

License

ISC

Available Tools

38 tools
create-mio-folderCreate MIO FolderC
Destructive

Create a new custom folder in MIO (internal messaging).

Inputs: name (required).

delete-mio-messageDelete MIO MessageA
Destructive

Move a MIO message to trash (not permanent). Use restore-mio-message to undo.

Inputs: message_id (required).

flag-mio-messageFlag MIO MessageC
Destructive

Set flag indicators (important, mark_unread) on a MIO message.

Inputs: important (required), message_id (required), mark_unread (required).

get-absencesGet AbsencesA
Read-only

Retrieve absence summaries for all courses in a given term or the current term.

Inputs: term_id.

get-assignment-detailGet Assignment DetailA
Read-only

Full detail of one assignment: deadline, instructions, what is in the hand-in deposit, teacher documents and corrected copies, with the file IDs get-assignment-file-link needs. A file in the deposit means something was uploaded, not that the work is finished.

Inputs: course_id (required), assignment_id (required), term_id.

get-assignments-summaryGet Assignments SummaryA
Read-only

Per-course assignment counts for a term, with the titles Lea still lists as to hand in. Only counts assignments teachers posted on Lea; an empty summary does not mean the student is caught up. Use get-course-assignments for deadlines and deposit contents.

Inputs: term_id.

get-calendarGet CalendarA
Read-only

Retrieve the real day-by-day calendar: classes, holidays, day swaps, cancelled classes, exams and deadlines. Prefer this over get-schedule for what happens on a given day. Exam and assignment dates only appear if the teacher entered them on Lea, so read the course syllabus for the full picture.

Inputs: page, range.

get-cancelled-classesGet Cancelled ClassesA
Read-only

Retrieve upcoming cancelled class sessions with time, course, teacher, room and any teacher comment.

Inputs: no named parameters.

get-college-documentsGet College DocumentsA
Read-only

List the official documents the college has sent to the student (admission letters, enrollment confirmations, notices, acknowledgments). Read-only: a mandatory document that has not been opened blocks every Lea tool until the student opens it in Omnivox themselves, and opening it is recorded on the student file, so this tool only names the document. Use it when another tool reports a mandatory college document block.

Inputs: no named parameters.

get-college-listGet College ListA
Read-only

Retrieve the list of colleges available to the user.

Inputs: no named parameters. Returns: count, colleges

get-college-newsGet College NewsB
Read-only

Retrieve the latest news and announcements from the college.

Inputs: no named parameters.

get-course-announcementsGet Course AnnouncementsC
Read-only

Retrieve announcements (communiqués) for a specific course.

Inputs: course_id (required), term_id.

get-course-assignmentsGet Course AssignmentsA
Read-only

List the assignments of a course with their deadline and what is in the hand-in deposit. A file in the deposit means something was uploaded, not that the work is finished. Incomplete by nature: many teachers never post assignments here, so an empty list does not mean there is no homework. Cross-check the course syllabus from get-course-documents.

Inputs: course_id (required), term_id.

get-course-documentsGet course documentsC
Read-only

Retrieve a list of documents for a specific course.

Inputs: course_id (required), term_id.

get-course-evalsGet Course GradesA
Read-only

Retrieve evaluations, grades and course summary for a specific course. Ungraded evaluations show no mark. Evaluations the teacher has not entered in Lea will not appear at all, so reconcile the list against the course syllabus.

Inputs: course_id (required), term_id.

get-course-infoGet Course InfoB
Read-only

Retrieve info about a specific course. Includes the course identity and teacher names.

Inputs: course_id (required), term_id. Returns: group, title, term_id, teachers, +2 more

get-course-peopleGet Course PeopleA
Read-only

List teachers and students for a specific course (max 75 results). Returns recipient IDs usable with send-mio-message.

Inputs: course_id (required).

get-courses-summaryGet Courses SummaryB
Read-only

Retrieve a summary of courses for a given term or the current term.

Inputs: term_id.

get-grades-summaryGet Grades SummaryA
Read-only

Retrieve a list of grades summaries for the user's courses in a given term or the current term.

Inputs: term_id.

get-mio-foldersGet MIO FoldersA
Read-only

Retrieve the list of MIO (internal messaging) folders and their unread counts. Folder IDs are string constants like SEARCH_FOLDER_MioRecu; pass them as folder_id to the other MIO tools.

Inputs: no named parameters.

get-mio-messagesGet MIO MessagesB
Read-only

Retrieve MIO messages from a folder. Supports pagination via last_id.

Inputs: count, last_id, folder_id.

get-online-formsGet Online FormsA
Read-only

List the online forms the college publishes in Omnivox (workshop registrations, course withdrawal requests, surveys, sign-ups), with whether each one is currently open. Read-only: filling a form stays in the Omnivox web portal.

Inputs: no named parameters.

get-overviewGet OverviewA
Read-only

Dashboard of what's actionable right now: today's schedule, per-course new items (documents, announcements, assignments, grades) with delta tracking, new MIO messages, upcoming evals, notifications, and featured college news. Best starting point to see what needs attention.

Inputs: term_id.

get-scheduleGet ScheduleA
Read-only

Retrieve the static weekly class schedule (timetable) for a given term or the current term. Same every week: it does not reflect holidays, day swaps or cancelled classes. Use get-calendar for those.

Inputs: term_id.

get-teachersGet TeachersA
Read-only

Fallback tool to get all teachers for a term. Returns names, departments, offices, phone numbers, and MIO IDs, but does NOT include which course each teacher teaches. Prefer get-course-people to look up teachers for a specific course — only use this tool if get-course-people fails or you need the full roster.

Inputs: term_id. Returns: term_id, teachers

get-termsGet TermsA
Read-only

Get the list of available academic terms (sessions) and the current default term, with human-readable names.

Inputs: no named parameters.

move-mio-messageMove MIO MessageB
Destructive

Move a MIO message to a different folder.

Inputs: folder_id (required), message_id (required).

read-mio-messageRead MIO MessageA
Read-only

Retrieve and read the full content of a single MIO message by its ID, from any folder. Returns the complete message body as plain text.

Inputs: message_id (required), mark_read.

reply-mio-messageReply to MIO MessageA
Destructive

Reply to a MIO message. Sends to the original sender, quotes the original under the reply and links the thread.

Inputs: message (required), message_id (required), subject, reply_all, +1 more.

restore-mio-messageRestore MIO MessageA

Restore a deleted MIO message from trash back to the inbox.

Inputs: message_id (required).

search-mio-messagesSearch MIO MessagesC
Read-only

Search MIO messages by text.

Inputs: query (required), folder_id.

search-peopleSearch PeopleA
Read-only

Search for people (students, teachers, employees) by name. Useful to find recipient IDs for sending MIO messages.

Inputs: query (required). Returns: count, results

send-mio-messageSend MIO MessageA
Destructive

Send a new MIO message. Use search-people first to get the recipient_id. Supports sending to multiple recipients at once.

Inputs: message (required), subject (required), recipient_id (required), hide_recipients.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 38 tools

    Disambiguation4/5

    Most tools target a clearly distinct resource+action, and the descriptions proactively disambiguate the risky pairs (get-schedule vs get-calendar, get-courses-summary vs get-grades-summary vs get-assignments-summary, get-teachers vs get-course-people as an explicit fallback). The main residual confusion is the cluster of five 'link' tools (get-document-link, get-assignment-file-link, get-assignment-submit-link, get-mio-attachment-link, get-service-link), which share a shape and expiry behavior and only differ by resource.

    Naming Consistency5/5

    Every name is lowercase kebab-case verb_noun: get-* for reads, and clear action verbs for mutations (send-, reply-, delete-, move-, flag-, restore-, create-, search-). No camelCase or snake_case mixing, and the verb choice consistently signals read vs write.

    Tool Count2/5

    38 tools is heavy even for a server spanning three subsystems (MIO messaging, Lea courses, college services). Several clusters could be consolidated — e.g. the five link-fetching tools could be one parameterized tool, and the summary tools (courses/grades/assignments) could share a parameterized surface — so the count is above what the scope strictly needs.

    Completeness4/5

    Coverage is strong: MIO has full lifecycle (list, search, read, send, reply, move, flag, trash, restore, folders, attachments) and the Lea/college side covers courses, people, documents, announcements, assignments, evals, grades, absences, calendar, forms and service links. Minor gaps remain — notifications are only surfaced inside get-overview with no dedicated retrieval tool, and there is no way to access a single announcement or document body without fetching the file.

    Maintenance

    ActivityActive
    ResponsivenessUsually handled

    Related MCP Connectors

    Related MCP Servers