Omnivox MCP

ケベック州のカレッジ学生ポータル(Omnivox/Lea)をMCPツールとRESTツールゲートウェイを通じて公開するMCPサーバーです。

Omnivoxにログインした永続的なPuppeteerブラウザを実行し、サイト自身のJavaScriptを介してリクエストを実行します。そのため、チャレンジレスポンス認証、Cookie、エンコーディングはすべてネイティブに処理されます。

機能

• 30 MCPツール — コース、成績、スケジュール、カレンダー、メッセージ(MIO)、ドキュメント、課題、カレッジニュース

• 2つのトランスポートモード — HTTP(デフォルト、MCP-over-HTTPを備えたExpressサーバー + RESTツールゲートウェイ)またはstdio (非推奨、推奨されません)

• RESTツールゲートウェイ — すべてのMCPツールを非MCPエージェント向けにプレーンなHTTPエンドポイントとして公開

• ファイルダウンロード — 直接バイナリまたは一時的なブラウザ向けリンク(15分TTL)

• 内部メッセージング — MIOメッセージの読み取り、検索、送信、フラグ、移動、削除

• 永続セッション — Chromeプロファイルは再起動後も維持され、繰り返しログインする必要はありません

Related MCP server: unofficial-magister-mcp

クイックスタート

# 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モード(デフォルト): /mcp?key=... でMCP-over-HTTPを提供するExpressサーバーと、RESTツールゲートウェイを起動します。アクセスキーは ~/.omnivox/accessKey.txt に自動生成されます。

stdioモード (非推奨、推奨されません): MCPクライアントがサーバーをサブプロセスとして起動し、stdin/stdoutで通信します。Expressサーバーもアクセスキーも不要です。

各インスタンスは1つのOmnivoxアカウントを提供します。サーバーは、ログインしたアカウントに紐づく単一のブラウザセッションを維持します。

再認証

セッションが期限切れになった場合や、別のアカウントにログインする必要がある場合は、セッションデータをリセットしてElectronアプリを再実行してください:

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 は ~/.omnivox/browser/、cookies.json、config.json を削除し、次回起動時にサーバーが新規状態で起動するようにします。

設定

これらを環境変数として、またはプロジェクトルートの .env ファイルに設定します:

使い方

MCP(AIアシスタント向け)

stdioモード (非推奨、推奨されません): MCPクライアント設定にサーバーを追加します — サーバーをサブプロセスとして起動します。npm run start:stdio を使用してください。接続設定については AGENT_SETUP.md を参照してください。

HTTPモード: Streamable HTTPトランスポートを介してMCPクライアントを http://localhost:3000/mcp?key=YOUR_KEY に接続します。

どちらの方法でも、AIは全30ツールにアクセスできます — 成績、スケジュール、課題、メッセージについて自然言語で質問できます。

RESTツールゲートウェイ(HTTPモード)

MCPをサポートしないエージェントやアプリ向けに、すべてのツールがプレーンなHTTPエンドポイントとして公開されます:

# 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 '{}'

ツールエンドポイントは Content-Type ヘッダーに関係なくJSONボディを受け入れます — 明示的に設定する必要はありません。

Omnivoxプロキシ(HTTPモード)

サーバーは /Mobl/* でパススループロキシを公開し、認証済みブラウザセッションを通じてリクエストをOmnivoxのモバイルAPIに直接転送します。任意のHTTPメソッドとコンテンツタイプがサポートされています。

# 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 '{}'

これは、MCPツールでラップされていないOmnivoxエンドポイントを呼び出す必要がある場合に便利です。

独自プロジェクトの構築

RESTツールゲートウェイはAIのためだけではありません — あらゆるプロジェクトで使用できる完全なOmnivox APIです:

• 成績ダッシュボード — 成績をカスタムWebアプリやスプレッドシートに取り込む

• スケジュールウィジェット — 週間タイムテーブルをホーム画面やデスクトップウィジェットに表示する

• 課題トラッカー — 新しい課題や今後の締め切りの通知を構築する

• Discord/Slackボット — 新しい成績やメッセージが届いたら通知を受け取る

• モバイルアプリ — 自分が気にする機能だけを備えたカスタムOmnivoxクライアントを構築する

• データエクスポート — 成績、ドキュメント、メッセージを自分の記録用にアーカイブする

HTTPリクエストを行える任意の言語で動作します — Python、JavaScript、Swift、Kotlin、Goなど、お好みの言語で問題ありません。GET /tools を使用して、利用可能なすべてのツールとその入力スキーマを確認できます。

ドキュメント

完全なドキュメントはWikiを参照してください:

• Setup — 前提条件、インストール、環境変数

• Architecture — システムの構造

• MCP Tools — パラメータ付きの全30ツール

• REST Tool Gateway — 非MCPエージェント向けのツールゲートウェイの使用方法

• Authentication — アクセスキー、Webトークン、セッション管理

これは安全ですか?

私たちはあなたのパスワードやデータを見ることはありません。 すべてはあなたのマシン(またはあなた自身のサーバー)上でローカルに実行されます:

• 自分でログインします — Electronアプリを通じて、Omnivoxの公式ログインページに直接パスワードを入力します。このプロジェクトはあなたのパスワードを要求、保存、送信することは一切ありません。

• 外部サーバーはありません。 MCPサーバーは完全にあなたのマシン上で実行されます。あなたのデータがサードパーティのサービスを経由することはありません — すべてのリクエストはあなたのサーバーとOmnivoxの間で直接行われます。

• セッションはローカルに保持されます。 ブラウザセッションとCookieはディスク上の ~/.omnivox/ に保存されます。アクセスできるのはあなただけです。

• オープンソース。 コードベース全体がここにあり、誰でも検査できます。隠れたネットワーク呼び出し、分析、テレメトリはありません。

セキュリティのベストプラクティス

• HTTPSなしでサーバーを公開しないでください。 TLSを使用したリバースプロキシ(例: Nginx)を使用してください。サンプル設定はSetup wikiを参照してください。

• ~/.omnivox/ を非公開に保ってください。 そこにはOmnivoxのセッションとアクセスキーが含まれています。accessKey.txt はパスワードのように扱い、誰とも共有しないでください。

• 詳細はSecurity Precautionsを参照してください。

免責事項

このプロジェクトは非公式であり、Skytech Communications、Omnivox、またはケベック州のいずれのカレッジとも提携、承認、関連していません。個人および教育目的でのみ、現状のまま提供されます。自己責任で使用してください — 著者は、アカウント制限、データ損失、所属機関の利用規約違反など、使用によって生じるいかなる結果についても責任を負いません。

ライセンス

ISC