Omnivox MCP

[퀘벡 대학 학생 포털(Omnivox/Lea)을 MCP 도구 및 REST 도구 게이트웨이를 통해 노출하는 MCP 서버입니다.](https://modelcontextprotocol.io/)

Omnivox에 로그인된 영구 Puppeteer 브라우저를 실행하며 사이트 자체 JavaScript를 통해 요청을 실행하므로 챌린지-응답 인증, 쿠키, 인코딩이 모두 기본적으로 처리됩니다.

기능

• 30가지 MCP 도구 — 강좌, 성적, 일정, 캘린더, 메시지(MIO), 문서, 과제, 대학 소식

• 두 가지 전송 모드 — HTTP(기본, MCP-over-HTTP + REST 도구 게이트웨이를 갖춘 Express 서버) 또는 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 및 REST 도구 게이트웨이를 제공하는 Express 서버를 시작합니다. 액세스 키는 ~/.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 '{}'

tools 엔드포인트는 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입니다:

• 성적 대시보드 — 성적을 맞춤 웹 앱이나 스프레드시트로 가져오기

• 일정 위젯 — 주간 시간표를 홈 화면 또는 데스크톱 위젯에 표시

• 과제 추적기 — 새 과제 또는 다가오는 마감일에 대한 알림 구축

• Discord/Slack 봇 — 새 성적이나 메시지가 도착하면 알림 받기

• 모바일 앱 — 관심 있는 기능만 갖춘 맞춤형 Omnivox 클라이언트 구축

• 데이터 내보내기 — 성적, 문서, 메시지를 개인 기록용으로 보관

HTTP 요청을 보낼 수 있는 모든 언어로 작동합니다 — Python, JavaScript, Swift, Kotlin, Go 등 선호하는 언어를 사용하세요. GET /tools를 사용하여 사용 가능한 모든 도구와 입력 스키마를 확인하십시오.

문서

전체 문서는 Wiki를 참조하십시오:

• 설정 — 전제 조건, 설치, 환경 변수

• 아키텍처 — 시스템 구조 방식

• MCP 도구 — 매개변수가 포함된 30가지 도구 전체

• REST 도구 게이트웨이 — 비-MCP 에이전트를 위한 도구 게이트웨이 사용

• 인증 — 액세스 키, 웹 토큰, 세션 관리

안전한가요?

우리는 귀하의 비밀번호나 데이터를 볼 수 없습니다. 모든 것이 귀하의 머신(또는 자체 서버)에서 로컬로 실행됩니다:

• 직접 로그인합니다 — Electron 앱을 통해 Omnivox 공식 로그인 페이지에 직접 비밀번호를 입력합니다. 이 프로젝트는 비밀번호를 요구하거나 저장하거나 전송하지 않습니다.

• 외부 서버 없음. MCP 서버는 전적으로 귀하의 머신에서 실행됩니다. 귀하의 데이터는 제3자 서비스를 통과하지 않습니다 — 모든 요청은 귀하의 서버와 Omnivox 사이에서 직접 이루어집니다.

• 세션은 로컬에 유지됩니다. 브라우저 세션과 쿠키는 디스크의 ~/.omnivox/에 저장됩니다. 오직 귀하만 접근할 수 있습니다.

• 오픈 소스. 전체 코드베이스가 검토할 수 있도록 여기에 있습니다. 숨겨진 네트워크 호출, 분석 또는 원격 측정이 없습니다.

보안 모범 사례

• HTTPS 없이 서버를 노출하지 마십시오. TLS와 함께 리버스 프록시(예: Nginx)를 사용하십시오. 샘플 구성은 설정 위키를 참조하십시오.

• ~/.omnivox/을(를) 비공개로 유지하십시오. 여기에는 Omnivox 세션과 액세스 키가 포함됩니다. accessKey.txt를 비밀번호처럼 취급하십시오 — 누구와도 공유하지 마십시오.

• 자세한 내용은 보안 주의사항을 참조하십시오.

면책 조항

이 프로젝트는 비공식 프로젝트이며 Skytech Communications, Omnivox 또는 퀘벡 소재 대학과 제휴, 보증 또는 관련이 없습니다. 개인적 및 교육적 목적으로만 있는 그대로 제공됩니다. 사용에 따른 모든 책임은 사용자에게 있습니다 — 저자는 계정 제한, 데이터 손실 또는 기관 서비스 약관 위반을 포함하되 이에 국한되지 않는 사용으로 인한 결과에 대해 책임을 지지 않습니다.

라이선스

ISC