Omnivox MCP

Un servidor MCP que expone los portales de estudiantes de colegios de Quebec (Omnivox/Lea) a través de herramientas MCP y una puerta de enlace de herramientas REST.

Ejecuta un navegador Puppeteer persistente con sesión iniciada en Omnivox, realizando solicitudes a través del propio JavaScript del sitio, por lo que la autenticación de desafío-respuesta, las cookies y la codificación se manejan de forma nativa.

Características

• 30 herramientas MCP — cursos, calificaciones, horario, calendario, mensajería (MIO), documentos, tareas, noticias del colegio

• Dos modos de transporte — HTTP (predeterminado, servidor Express con MCP sobre HTTP + puerta de enlace de herramientas REST) o stdio (obsoleto, no recomendado)

• Puerta de enlace de herramientas REST — todas las herramientas MCP expuestas como endpoints HTTP simples para agentes no MCP

• Descargas de archivos — binarios directos o enlaces temporales compatibles con navegador (TTL de 15 min)

• Mensajería interna — leer, buscar, enviar, marcar, mover y eliminar mensajes MIO

• Sesión persistente — el perfil de Chrome sobrevive a los reinicios, sin inicios de sesión repetidos

Related MCP server: unofficial-magister-mcp

Inicio rápido

# 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)

Modo HTTP (predeterminado): Inicia un servidor Express con MCP sobre HTTP en /mcp?key=... y una puerta de enlace de herramientas REST. La clave de acceso se genera automáticamente en ~/.omnivox/accessKey.txt.

Modo stdio (obsoleto, no recomendado): El cliente MCP inicia el servidor como subproceso y se comunica a través de stdin/stdout. Sin servidor Express, sin necesidad de clave de acceso.

Cada instancia sirve una cuenta de Omnivox. El servidor mantiene una única sesión de navegador vinculada a la cuenta con la que iniciaste sesión.

Reautenticación

Si tu sesión caduca o necesitas iniciar sesión con otra cuenta, restablece los datos de la sesión y vuelve a ejecutar la aplicación 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 elimina ~/.omnivox/browser/, cookies.json y config.json para que el servidor se inicie desde cero en el próximo lanzamiento.

Configuración

Establece estas variables de entorno o en un archivo .env en la raíz del proyecto:

Uso

MCP (para asistentes de IA)

Modo stdio (obsoleto, no recomendado): Añade el servidor a la configuración de tu cliente MCP: lo lanza como subproceso. Usa npm run start:stdio. Consulta AGENT_SETUP.md para la configuración de conexión.

Modo HTTP: Conecta tu cliente MCP a http://localhost:3000/mcp?key=YOUR_KEY mediante el transporte HTTP Streamable.

En cualquier caso, la IA obtiene acceso a las 30 herramientas — pregúntale sobre tus calificaciones, horario, tareas o mensajes en lenguaje natural.

Puerta de enlace de herramientas REST (modo HTTP)

Para agentes o aplicaciones que no admiten MCP, todas las herramientas se exponen como endpoints HTTP simples:

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

El endpoint de herramientas acepta cuerpos JSON independientemente de la cabecera Content-Type — no es necesario establecerla explícitamente.

Proxy de Omnivox (modo HTTP)

El servidor expone un proxy de paso en /Mobl/* que reenvía solicitudes directamente a la API móvil de Omnivox a través de la sesión de navegador autenticada. Se admite cualquier método HTTP y tipo de contenido.

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

Esto es útil cuando necesitas llamar a un endpoint de Omnivox que no está envuelto por una herramienta MCP.

Crea tus propios proyectos

La puerta de enlace de herramientas REST no es solo para IA — es una API completa de Omnivox que puedes usar en cualquier proyecto:

• Panel de calificaciones — lleva tus calificaciones a una aplicación web personalizada o una hoja de cálculo

• Widget de horario — muestra tu horario semanal en una pantalla de inicio o widget de escritorio

• Seguimiento de tareas — crea notificaciones para nuevas tareas o próximas fechas límite

• Bot de Discord/Slack — recibe notificaciones cuando lleguen nuevas calificaciones o mensajes

• Aplicación móvil — crea un cliente Omnivox personalizado solo con las funciones que te interesan

• Exportación de datos — archiva tus calificaciones, documentos y mensajes para tu propio registro

Cualquier lenguaje que pueda hacer solicitudes HTTP funciona — Python, JavaScript, Swift, Kotlin, Go, lo que prefieras. Usa GET /tools para descubrir todas las herramientas disponibles y sus esquemas de entrada.

Documentación

Consulta la Wiki para obtener la documentación completa:

• Configuración — requisitos previos, instalación, variables de entorno

• Arquitectura — cómo está estructurado el sistema

• Herramientas MCP — las 30 herramientas con parámetros

• Puerta de enlace de herramientas REST — uso de la puerta de enlace de herramientas para agentes no MCP

• Autenticación — claves de acceso, tokens web, gestión de sesiones

¿Es seguro?

Nunca vemos tu contraseña ni tus datos. Todo se ejecuta localmente en tu máquina (o en tu propio servidor):

• Inicias sesión tú mismo a través de la aplicación Electron: tu contraseña de Omnivox se introduce directamente en la página de inicio de sesión oficial de Omnivox. Este proyecto nunca solicita, almacena ni transmite tu contraseña.

• Sin servidores externos. El servidor MCP se ejecuta completamente en tu máquina. Tus datos nunca pasan por ningún servicio de terceros: todas las solicitudes van directamente entre tu servidor y Omnivox.

• La sesión permanece local. La sesión del navegador y las cookies se almacenan en ~/.omnivox/ en tu disco. Solo tú tienes acceso a ellas.

• Código abierto. Todo el código fuente está aquí para que lo inspecciones. No hay llamadas de red ocultas, análisis ni telemetría.

Buenas prácticas de seguridad

• Nunca expongas el servidor sin HTTPS. Usa un proxy inverso (p. ej. Nginx) con TLS. Consulta la wiki de Configuración para ver un ejemplo de configuración.

• Mantén ~/.omnivox/ privado. Contiene tu sesión de Omnivox y tu clave de acceso. Trata accessKey.txt como una contraseña: no la compartas con nadie.

• Consulta Precauciones de seguridad para más detalles.

Aviso legal

Este proyecto no es oficial y no está afiliado, respaldado ni asociado con Skytech Communications, Omnivox ni ningún colegio de Quebec. Se proporciona tal cual solo para uso personal y educativo. Úsalo bajo tu propio riesgo: los autores no son responsables de las consecuencias derivadas de su uso, incluidas, entre otras, restricciones de cuenta, pérdida de datos o violaciones de los términos de servicio de tu institución.

Licencia

ISC