Omnivox MCP

一个 MCP 服务器，通过 MCP 工具和 REST 工具网关公开魁北克大学学生门户（Omnivox/Lea）。

它运行一个持久化的 Puppeteer 浏览器，登录到 Omnivox，通过网站自身的 JavaScript 执行请求——因此质询-响应认证、cookie 和编码都得到原生处理。

特性

• 30 个 MCP 工具 — 课程、成绩、日程、日历、消息（MIO）、文档、作业、学院新闻

• 两种传输模式 — HTTP（默认，Express 服务器，支持 MCP-over-HTTP + REST 工具网关）或 stdio （已弃用，不推荐）

• REST 工具网关 — 所有 MCP 工具作为普通 HTTP 端点公开，供非 MCP 代理使用

• 文件下载 — 直接二进制或临时浏览器友好链接（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 模式（默认）：启动一个 Express 服务器，在 /mcp?key=... 提供 MCP-over-HTTP 和 REST 工具网关。访问密钥自动生成于 ~/.omnivox/accessKey.txt。

stdio 模式 （已弃用，不推荐）：MCP 客户端将服务器作为子进程启动，并通过 stdin/stdout 通信。无需 Express 服务器，无需访问密钥。

每个实例服务一个 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 头如何，tools 端点都接受 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：

• 设置 — 先决条件、安装、环境变量

• 架构 — 系统结构

• MCP 工具 — 所有 30 个工具及其参数

• REST 工具网关 — 为非 MCP 代理使用工具网关

• 认证 — 访问密钥、Web 令牌、会话管理

这安全吗？

我们永远不会看到您的密码或数据。 一切都在您的机器（或您自己的服务器）上本地运行：

• 您自己登录 通过 Electron 应用——您的 Omnivox 密码直接在官方 Omnivox 登录页面上输入。本项目从不要求、存储或传输您的密码。

• 没有外部服务器。 MCP 服务器完全在您的机器上运行。您的数据永远不会经过任何第三方服务——所有请求直接发生在您的服务器和 Omnivox 之间。

• 会话保持本地。 浏览器会话和 cookie 存储在您磁盘上的 ~/.omnivox/ 中。只有您可以访问它们。

• 开源。 整个代码库都在这里供您检查。没有隐藏的网络调用、分析或遥测。

安全最佳实践

• 切勿在没有 HTTPS 的情况下暴露服务器。 使用带有 TLS 的反向代理（例如 Nginx）。有关示例配置，请参阅 设置 Wiki。

• 保持 ~/.omnivox/ 私有。 它包含您的 Omnivox 会话和访问密钥。将 accessKey.txt 视为密码——不要与任何人共享。

• 有关更多详细信息，请参阅 安全预防措施。

免责声明

本项目是非官方的，与 Skytech Communications、Omnivox 或任何魁北克大学没有关联、认可或联系。它按原样提供，仅供个人和教育使用。使用风险自负——作者不对因使用而产生的任何后果负责，包括但不限于账户限制、数据丢失或违反您所在机构的服务条款。

许可证

ISC