ManageBac MCP Server

AI 에이전트(Claude Code, Claude Desktop, OpenCode, ChatGPT 등)가 ManageBac 계정의 마감일, 성적, 공지사항, 자료, 과제 제출을 읽고 상호작용할 수 있게 해주는 로컬 MCP 서버입니다.

실제 브라우저 창을 통해 로그인하고(한 번만 로그인하면 됩니다), 세션을 로컬에 저장한 뒤 재사용합니다 — 비밀번호는 저장되거나 어디로도 전송되지 않습니다.

Tools

• managebac_get_classes — 수업 목록을 표시합니다

• managebac_get_all_deadlines / managebac_get_class_deadlines — 다가오는, 지난, 기한이 지난 과제를 표시합니다

• managebac_get_grades / managebac_get_class_grades / managebac_get_recent_class_grades — 성적 항목을 표시합니다

• managebac_get_gpa / managebac_get_class_gpa — 페이지에 표시된 GPA를 표시합니다(추정 값 아님)

• managebac_get_class_grade_weights — 특정 수업의 카테고리 가중치를 표시합니다

• managebac_get_announcements — 학교 및 수업 페이지의 공지사항/알림을 표시합니다

• managebac_get_class_resources — 특정 수업의 다운로드 가능한 파일/자료(수업 과제, 학습 자료)를 표시합니다

• managebac_download_file — 파일(첨부 파일 또는 리소스 href)을 base64로 다운로드합니다

• managebac_get_assignment_details — 특정 과제의 루브릭, 지시사항, 첨부 파일을 표시합니다

• managebac_submit_assignment — 파일(디스크 또는 ChatGPT처럼 로컬 파일 접근 권한이 없는 클라이언트를 위한 base64)이나 텍스트를 과제에 첨부합니다. 항상 먼저 dry-run을 수행합니다

• managebac_get_cas_info / managebac_get_ee_info — 잠금 해제된 CAS/Extended Essay 성찰을 표시합니다

• managebac_check_session / managebac_runtime_info — 세션 상태 및 프로세스 진단 정보를 표시합니다

• managebac_list_links / managebac_debug_snapshot — 페이지 경로를 찾기 위한 디버깅 도우미입니다

공지사항과 자료는 최선 노력(best-effort) 방식입니다. ManageBac의 페이지 구조는 학교마다 다르므로, 결과가 부실해 보이면 에이전트에게 managebac_list_links 또는 managebac_debug_snapshot을 사용해 올바른 페이지를 찾은 다음 path로 전달하도록 요청하세요.

Related MCP server: Chrome MCP Server

Install

Requires Node.js 20+.

git clone https://github.com/DH4410/managebac-mcp-server.git
cd managebac-mcp-server
npm install
npm run build
npm run install-browser   # first time only, installs Chromium for Playwright

env 파일을 복사하고 학교의 ManageBac URL을 설정하세요:

cp .env.example .env

MANAGEBAC_BASE_URL=https://your-school.managebac.com

한 번 로그인하세요(실제 브라우저 창이 열리고, 세션을 저장한 다음 닫힙니다):

npm run login

AI 에이전트에 연결하기

대부분의 MCP 클라이언트(Claude Code, Claude Desktop, OpenCode, Cursor)는 MCP 서버를 로컬 프로세스로 실행합니다. 해당 클라이언트의 MCP 구성에 다음과 같이 추가하세요:

{
  "mcpServers": {
    "managebac": {
      "command": "node",
      "args": ["/absolute/path/to/managebac-mcp-server/dist/index.js"],
      "env": {
        "MANAGEBAC_BASE_URL": "https://your-school.managebac.com",
        "MANAGEBAC_STORAGE_STATE": "/absolute/path/to/managebac-mcp-server/.managebac/storage-state.json"
      }
    }
  }
}

특히 Claude Code의 경우, 저장소 루트의 .mcp.json에 이 내용을 넣은 다음 /mcp를 실행하고 서버를 승인하세요.

ChatGPT에 연결하기

ChatGPT는 MCP 서버를 URL로만 연결합니다(로컬 프로세스는 불가). 따라서 로컬 서버에는 일시적인 공개 URL과 이를 보호할 비밀 토큰이 필요합니다. ManageBac 로그인 정보는 여전히 사용자 컴퓨터를 벗어나지 않습니다. 터널을 통과하는 것은 도구 응답뿐이고, 그것도 사용 중일 때만입니다.

가장 빠른 방법 — 명령 하나:

npm install cloudflared   # one-time; downloads the cloudflared binary (~40MB)
npm run chatgpt

이 명령은 서버를 빌드하고, HTTP 모드로 시작하며, Cloudflare quick tunnel을 열고 다음과 같은 블록을 출력합니다:

=================================================
 ChatGPT connector settings
=================================================
 URL:   https://random-words.trycloudflare.com/mcp
 Auth:  Bearer token
 Token: 9f2a1c...
=================================================

ChatGPT에서: 설정 → 커넥터 → 고급/개발자 모드 → 커넥터 추가를 선택한 다음, URL을 붙여넣고 인증을 표시된 토큰을 사용한 Bearer 토큰으로 설정하세요.

ChatGPT에서 접근 권한을 유지하려는 동안 터미널을 열어 두세요. 터미널을 닫으면(Ctrl+C) 터널과 서버가 모두 중지됩니다. URL과 토큰은 명령을 실행할 때마다 새로 생성되므로, 재시작 후에는 ChatGPT에 다시 붙여넣어야 합니다.

수동 방법(cloudflared 패키지를 추가하고 싶지 않다면): .env에서 MCP_TRANSPORT=http, MCP_HTTP_PORT=3939, MCP_HTTP_TOKEN=<a long random value>를 설정하고 npm start를 실행하세요. 그런 다음 HTTPS 터널 도구(예: 이미 cloudflared를 별도로 설치한 경우 cloudflared tunnel --url http://localhost:3939)를 3939 포트에 연결하고, 같은 방식으로 ChatGPT에서 <tunnel-url>/mcp와 토큰을 사용하세요.

Notes

• .env 및 .managebac/(저장된 세션)은 git에서 무시됩니다 — 절대 커밋하지 마세요.

• 코드를 수정하거나 다시 로그인한 경우 MCP 클라이언트를 재시작하여 새 프로세스를 인식하게 하세요.

• ManageBac이 계정을 잠그면 자동 로그인 재시도를 중단하고 대신 npm run login(수동)을 사용하세요.

문제 해결

마감일이나 GPA가 잘못 표시되면 디버그 도구를 사용해 스크레이퍼가 무엇을 찾고 있는지 확인하세요:

managebac_list_links({ "match": "task" })
managebac_debug_snapshot({ "path": "/student/tasks_and_deadlines?view=upcoming" })

선택 사항: 자동 비밀번호 로그인

기본적으로 꺼져 있습니다(수동 로그인이 더 안전합니다). 활성화하려면 .env에 설정하세요:

MANAGEBAC_LOGIN_MODE=password
MANAGEBAC_EMAIL=your.email@example.com
MANAGEBAC_PASSWORD=your-password