omnivox-mcp
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 3000The 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 -dThe 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 startnpm 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 |
|
| Server port |
|
| Data directory for config, cookies, browser profile, and access key |
| (none) | Contents of |
| (none) | Extra Chrome flags appended to the default launch arguments, space-separated. Useful in Docker where Chrome runs as root and needs |
|
| When |
| (disabled) | Interval in minutes between automatic page refreshes to keep the Omnivox session alive. Recommended for long-lived instances (e.g. |
| (none) | Optional. Public base URL that enables download link generation ( |
|
| When |
|
| 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
GetOffreServicedescribes 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:
Delete
accessKey.txt(a new key is generated on restart), andnpm 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 toolscreate-mio-folderCreate MIO FolderCDestructive
Create a new custom folder in MIO (internal messaging).
Inputs: name (required).
delete-mio-messageDelete MIO MessageADestructive
Move a MIO message to trash (not permanent). Use restore-mio-message to undo.
Inputs: message_id (required).
flag-mio-messageFlag MIO MessageCDestructive
Set flag indicators (important, mark_unread) on a MIO message.
Inputs: important (required), message_id (required), mark_unread (required).
get-absencesGet AbsencesARead-only
Retrieve absence summaries for all courses in a given term or the current term.
Inputs: term_id.
get-assignment-detailGet Assignment DetailARead-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-assignment-file-linkGet Assignment FileARead-only
Fetch an assignment file (teacher document, student submission, or corrected copy). In HTTP mode with MCP_SERVER_URL set, returns a browser link that expires after 15 minutes; otherwise saves the file locally and returns its path. Get file IDs and roles from get-assignment-detail.
Inputs: role (required), file_id (required), course_id (required), assignment_id (required), +1 more.
get-assignments-summaryGet Assignments SummaryARead-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-assignment-submit-linkGet Assignment Submit LinkARead-onlyIdempotent
Get a short link that opens the Omnivox hand-in page for an assignment, already logged in. Give it to the user so they can upload their file in their own browser — this tool never submits anything itself. Link expires after 15 minutes. Fails if online submission is closed for the assignment, or if the server has no public URL (MCP_SERVER_URL).
Inputs: course_id (required), assignment_id (required), term_id. Returns: msg, url
get-calendarGet CalendarARead-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 ClassesARead-only
Retrieve upcoming cancelled class sessions with time, course, teacher, room and any teacher comment.
Inputs: no named parameters.
get-college-documentsGet College DocumentsARead-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 ListARead-only
Retrieve the list of colleges available to the user.
Inputs: no named parameters. Returns: count, colleges
get-college-newsGet College NewsBRead-only
Retrieve the latest news and announcements from the college.
Inputs: no named parameters.
get-course-announcementsGet Course AnnouncementsCRead-only
Retrieve announcements (communiqués) for a specific course.
Inputs: course_id (required), term_id.
get-course-assignmentsGet Course AssignmentsARead-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 documentsCRead-only
Retrieve a list of documents for a specific course.
Inputs: course_id (required), term_id.
get-course-evalsGet Course GradesARead-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 InfoBRead-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 PeopleARead-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 SummaryBRead-only
Retrieve a summary of courses for a given term or the current term.
Inputs: term_id.
get-document-linkGet Lea DocumentBRead-only
Fetch a Lea document. In HTTP mode with MCP_SERVER_URL set, returns a browser link that expires after 15 minutes; otherwise saves the file locally and returns its path. Marks the document as read on Omnivox, so use get-course-documents first if you are only browsing.
Inputs: course_id (required), document_id (required), term_id.
get-grades-summaryGet Grades SummaryARead-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-attachment-linkGet MIO AttachmentARead-only
Fetch a MIO message attachment. In HTTP mode with MCP_SERVER_URL set, returns a browser link that expires after 15 minutes; otherwise saves the file locally and returns its path. Get attachment IDs from read-mio-message.
Inputs: message_id (required), attachment_id (required).
get-mio-foldersGet MIO FoldersARead-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 MessagesBRead-only
Retrieve MIO messages from a folder. Supports pagination via last_id.
Inputs: count, last_id, folder_id.
get-online-formsGet Online FormsARead-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 OverviewARead-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 ScheduleARead-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-service-linkGet Omnivox Service LinkARead-only
Get a pre-authenticated link to an Omnivox web-only service (lockers, transcript, progression chart, advisor appointments, ...). These services have no API here, so the link is how to reach them. Open it yourself to read the page for the user, or give it to the user. Any action on the page needs the user's explicit authorization for that specific action. It logs the browser into the user's full Omnivox account, so treat it like a password. Expires after 15 minutes.
Inputs: service (required). Returns: msg, url
get-teachersGet TeachersARead-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 TermsARead-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 MessageBDestructive
Move a MIO message to a different folder.
Inputs: folder_id (required), message_id (required).
read-mio-messageRead MIO MessageARead-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 MessageADestructive
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 MessagesCRead-only
Search MIO messages by text.
Inputs: query (required), folder_id.
search-peopleSearch PeopleARead-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 MessageADestructive
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
Scored across 38 tools
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.
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.
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.
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
Related MCP Connectors
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Connect any AI agent to 1,000+ apps and 27,000+ actions through one remote MCP server (OAuth).
Related MCP Servers
- FlicenseBqualityDmaintenanceAn MCP server that enables AI agents to authenticate with and interact with Open eClass platform instances, supporting UoA's SSO authentication system for retrieving course information and performing basic platform operations.48-
- AlicenseAqualityDmaintenanceAn MCP server for accessing Dutch school schedules from Magister. Enables Claude and other MCP-compatible AI assistants to query school schedules, drop-off times, and pick-up times.48 npm7MIT
- AlicenseNot gradedqualityBmaintenanceAn MCP server that connects AI assistants to university D2L Brightspace and Piazza, enabling query of courses, grades, assignments, deadlines, files, and Piazza posts.7MIT
- AlicenseNot gradedqualityDmaintenanceMCP server that integrates GitHub, Brightspace, Outlook, and local files, enabling natural language queries for assignments, grades, emails, calendar events, repositories, and file operations.MIT