ku-portal-mcp

PyPI version Python License: MIT

고려대학교 KUPID 포털 MCP 서버 — Claude Code에서 대학 생활에 필요한 정보를 바로 조회

"공지사항 보여줘", "도서관 빈자리 있어?", "이번 주 과제 뭐 있어?" 같은 자연어로 포털과 LMS를 사용할 수 있습니다.

"수업 뭐가 있나?" — LMS 수강과목 조회

"공지사항 보여줘" — 전체 + 학과 공지 조회

이런 걸 할 수 있어요

1. 공지사항 / 학사일정 / 장학공지

KUPID 포털의 각종 게시판을 조회하고, 키워드로 검색할 수 있습니다.

> 최근 공지사항 보여줘
> "수강신청" 관련 공지 검색해줘
> 이번 달 학사일정 알려줘
> 장학금 관련 공지 있어?
> 공지사항 3번째 글 상세 내용 보여줘

• 공지사항, 학사일정, 장학공지 목록 조회 + 상세 내용 열람
• 제목 기준 키워드 통합 검색 (공지/일정/장학 동시 검색 가능)
• 첨부파일 목록, 작성자, 작성일 등 메타 정보 포함

2. 도서관 좌석 현황 (로그인 불필요)

6개 도서관, 53개 열람실의 실시간 좌석 현황을 확인합니다. 로그인 없이 바로 조회 가능합니다.

> 중앙도서관 빈자리 몇 개야?
> 과학도서관 좌석 현황 보여줘
> 전체 도서관 좌석 현황 알려줘
> 노트북 사용 가능한 열람실 어디야?

• 대상 도서관: 중앙도서관, 중앙광장, 백주년기념 학술정보관, 과학도서관, 하나스퀘어, 법학도서관
• 열람실별 총 좌석 / 사용 중 / 잔여 좌석 실시간 표시
• 노트북 허용 여부, 운영시간 정보 포함
• 전체 도서관 합산 이용률(%) 제공

3. 수업시간표 + ICS 내보내기

포털에 등록된 개인 수업시간표를 조회하고, 구글 캘린더 등에 추가할 수 있는 ICS 파일로 내보냅니다.

> 이번 주 시간표 보여줘
> 월요일 수업 뭐 있어?
> 시간표를 ICS 파일로 만들어줘
> 오늘 수업 몇 시에 시작해?

• 월~금 요일별 조회 또는 전체 주간 시간표 한번에 보기
• 교시 → 실제 시간 자동 변환 (1교시=09:0010:15, 2교시=10:3011:45 ...)
• ICS 캘린더 파일 생성 → 구글 캘린더, Apple 캘린더에 바로 추가 가능
• 과목명, 강의실, 교시 정보 포함

4. 내 수강신청 내역

수강신청한 과목의 학수번호, 강의시간, 강의실, 교수 등 상세 정보를 확인합니다. 대학원 과목도 지원합니다.

> 내 수강과목 보여줘
> 이번 학기 뭐 듣고 있어?
> 내 수업 강의실 어디야?
> 총 몇 학점 신청했어?

• 학수번호, 분반, 이수구분, 교과목명, 담당교수, 학점, 강의시간/강의실
• 재수강 여부, 신청 상태 확인
• 총 신청 학점 합산
• 대학원 과목 포함 (기존 시간표/개설과목 검색으로 안 나오던 과목)

5. 전체 성적 / 누적 GPA / 취득학점

KUPID의 전체성적조회 화면에서 최종 확정 성적과 누계 성적을 확인합니다.

> 전체 성적 보여줘
> 누적 GPA 얼마야?
> 취득학점 얼마나 됐어?
> 2024학년도 2학기 성적만 보여줘

• 최종 확정된 전체 성적 조회 (년도/학기별 필터 지원)
• 과목별 점수, 등급, 평점, 재수강 반영 여부 확인
• 누적 GPA / 총평점 / 취득학점 조회
• 졸업요건 계산에 활용 가능한 원본 성적 데이터 제공

6. 개설과목 검색 + 강의계획서

학과/단과대별 개설 과목을 검색하고, 강의계획서를 조회합니다.

> 정보대학 컴퓨터학과 개설과목 보여줘
> 이번 학기 경영대학에 어떤 학과가 있어?
> COSE101 강의계획서 보여줘
> AAI110 강의계획서 보여줘
> 공과대학 개설과목 검색해줘
> SW·AI융합대학원 인공지능융합학과 개설과목 보여줘

• 단과대 → 학과 → 과목 단계적 검색 (코드를 몰라도 됩니다)
• 서울캠퍼스 학부 22개 단과대 + 대학원 38개 단과대 지원
  • 학부 예: 경영, 문과, 정보, 공과, 이과, 미디어, 사범, 보건과학, 학부대학 등
  • 대학원 예: SW·AI융합, 융합데이터과학, 정보보호, 공학, 경영전문, 의학전문 등
• is_grad: true 파라미터로 대학원 모드 전환 (kupid_search_courses(is_grad=true))
• 과목별 학수번호, 분반, 교수명, 학점, 시간표 정보
• 강의계획서 조회: 학수번호로 교수/학점/시간표 등 과목 정보 자동 추출 (90+ 학과 매핑)

7. 강의실 시간표 — "이 강의실 오늘 비었나?"

특정 건물·호실에 잡힌 정규 수업을 학부+대학원 통합으로 조회합니다. 대기 가능 시간대 확인용.

> 애기능 301호 오늘 수업 뭐 있어?
> 정운오IT교양관 B102 화요일 시간표
> 정보통신관 604호 비는 시간 있어?

• 건물명·호실 부분일치 (예: building="애기능", room="301")
• 학부 22개 + 대학원 38개 단과대 전수 호출 → 결과 병합 (병렬, 약 30~60초)
• 요일·교시·시간(HH:MM)·학수번호·강의명·교수·학과/대학·구분(학부/대학원) 반환
• 시간순 정렬 + 중복 제거
• ⚠️ 정규 수업만 잡힙니다. 학회·세미나·임시 행사 등 비정규 점유는 spacek.korea.ac.kr 공간예약 시스템 별도 확인 필요

8. Canvas LMS — 수강과목 / 과제 / 강의자료

고려대학교 Canvas LMS(mylms.korea.ac.kr)에 접속하여 수강 정보를 조회합니다.

> LMS에 어떤 과목 듣고 있어?
> 딥러닝 과제 목록 보여줘
> 아직 안 낸 과제 있어?
> 자연어처리 강의자료 보여줘
> 텍스트마이닝 1주차 PDF 다운로드해줘
> 이번 주 제출할 과제 뭐야?
> LMS 대시보드 보여줘
> 딥러닝 성적 어때?
> 과제 제출 현황 보여줘
> 퀴즈 일정 있어?

• 수강과목 목록: 현재 학기 수강 중인 과목과 학기 정보
• 과제 목록: 과목별 과제, 제출 기한, 배점, 제출 방식 확인
• 강의자료(모듈): 주차별 강의 모듈과 포함된 자료(강의 영상, PDF, 퀴즈 등)
• 파일 다운로드: 강의자료 PDF 등을 지정한 로컬 디렉토리에 직접 저장
• 게시판 조회: Q&A 게시판 / 강의자료실 등 교수님이 직접 올리는 자료까지 탐색
• 할 일 목록: 마감이 다가오는 과제와 이벤트를 한눈에
• 대시보드: 수강 과목 카드 + 과목별 공지사항 모아보기
• 성적/점수 조회: 과목별 현재 점수, 최종 점수, 학점 확인
• 과제 제출 현황: 제출 여부, 채점 점수, 지각/미제출 상태 확인
• 퀴즈/시험 목록: 퀴즈 일정, 시간제한, 문항 수 확인

더 많은 사용 예시는 EXAMPLES.md를 참고하세요.

---

전체 Tool 목록

#	Tool	설명	인증
1	kupid_login	포털 로그인 / 세션 확인	SSO
2	kupid_get_notices	공지사항 목록	SSO
3	kupid_get_notice_detail	공지사항 상세	SSO
4	kupid_get_schedules	학사일정 목록	SSO
5	kupid_get_schedule_detail	학사일정 상세	SSO
6	kupid_get_scholarships	장학공지 목록	SSO
7	kupid_get_scholarship_detail	장학공지 상세	SSO
8	kupid_search	공지/일정/장학 통합 검색	SSO
9	kupid_get_library_seats	도서관 열람실 좌석 현황	불필요
10	kupid_get_timetable	개인 수업시간표 + ICS 내보내기	SSO
11	kupid_search_courses	개설과목 검색 (학부/대학원, is_grad 옵션)	SSO
12	kupid_get_syllabus	강의계획서 조회	SSO
13	kupid_my_courses	내 수강신청 내역 (학수번호/시간/강의실)	SSO
14	kupid_room_schedule	건물/호실의 정규 수업 시간표 (학부+대학원 통합)	SSO
15	kupid_get_all_grades	전체 성적 / 누적 GPA / 취득학점 조회	SSO
16	kupid_lms_courses	LMS 수강과목 목록	KSSO
17	kupid_lms_assignments	LMS 과제 목록 (과목별)	KSSO
18	kupid_lms_modules	LMS 강의자료 (주차별 모듈)	KSSO
19	kupid_lms_todo	LMS 할 일 / 다가오는 이벤트	KSSO
20	kupid_lms_dashboard	LMS 대시보드 + 공지사항	KSSO
21	kupid_lms_grades	LMS 성적/점수 조회	KSSO
22	kupid_lms_submissions	LMS 과제 제출 현황	KSSO
23	kupid_lms_quizzes	LMS 퀴즈/시험 목록	KSSO
24	kupid_lms_download_file	LMS 강의자료 파일 다운로드 (PDF 등)	KSSO
25	kupid_lms_list_boards	LMS 과목 게시판 목록 (Q&A, 강의자료실 등)	KSSO
26	kupid_lms_list_board_posts	게시판 게시글 목록	KSSO
27	kupid_lms_get_board_post	게시글 상세 + 첨부파일 (canvas_file_id 포함)	KSSO

인증 안내: SSO = KUPID 포털 인증, KSSO = 고려대 통합 SSO (Canvas LMS용). 모두 같은 ID/PW를 사용하며, 환경변수만 설정하면 자동으로 로그인됩니다.

설치

방법 1: uvx (권장)

설치 없이 항상 최신 버전을 실행합니다. Claude Code와의 호환성이 가장 좋습니다.

uvx ku-portal-mcp

방법 2: pip

pip install ku-portal-mcp

방법 3: 소스에서 설치

git clone https://github.com/SonAIengine/ku-portal-mcp.git
cd ku-portal-mcp
pip install -e .

Claude Code에서 사용하기

1. MCP 서버 등록

claude mcp add CLI 명령으로 등록합니다:

uvx 사용 (권장):

claude mcp add -s user \
  -e KU_PORTAL_ID=your-kupid-id \
  -e KU_PORTAL_PW=your-kupid-password \
  ku-portal \
  uvx ku-portal-mcp@latest

pip으로 설치한 경우:

claude mcp add -s user \
  -e KU_PORTAL_ID=your-kupid-id \
  -e KU_PORTAL_PW=your-kupid-password \
  ku-portal \
  ku-portal-mcp

• KU_PORTAL_ID와 KU_PORTAL_PW는 KUPID 포털 로그인에 사용하는 학번과 비밀번호입니다.
• -s user는 글로벌(모든 프로젝트) 등록입니다. 특정 프로젝트에서만 사용하려면 -s project로 변경하세요.

2. 설정 적용

MCP 서버 설정은 Claude Code 시작 시점에 1회 로드됩니다.

• 방법 A: Claude Code를 재시작
• 방법 B: 세션 내에서 /mcp 명령어 실행 → MCP 서버 추가/재시작을 재시작 없이 바로 적용

3. 동작 확인

Claude Code에서 아래와 같이 자연어로 물어보세요:

> 도서관 좌석 현황 보여줘

로그인 없이 바로 결과가 나오면 정상적으로 설치된 것입니다.

> 최근 공지사항 보여줘
> 이번 주 과제 뭐 있어?
> 내 시간표 보여줘

4. /ku 슬래시 커맨드 활용

examples/commands/ku.md를 Claude Code의 커스텀 슬래시 커맨드로 등록하면, /ku 한 줄로 포털 조회를 더 빠르게 할 수 있습니다.

설치: examples/commands/ku.md 파일을 프로젝트의 .claude/commands/ 또는 ~/.claude/commands/에 복사합니다.

# 글로벌 커맨드로 등록 (모든 프로젝트에서 사용)
mkdir -p ~/.claude/commands
cp examples/commands/ku.md ~/.claude/commands/ku.md

사용 예시:

> /ku 도서관
> /ku 공지 수강신청
> /ku 과제
> /ku 시간표
> /ku 성적
> /ku 검색 장학금

슬래시 커맨드는 필요한 MCP tool만 자동으로 허용하므로, 자연어 질의보다 빠르고 정확하게 동작합니다. 자세한 키워드 목록은 examples/commands/ku.md를 참고하세요.

프로젝트 구조

ku_portal_mcp/
├── server.py      # MCP 서버 + 21개 tool 등록
├── auth.py        # KUPID SSO 로그인, 세션 캐싱 (30분 TTL)
├── scraper.py     # GRW 공지/일정/장학 파싱
├── library.py     # 도서관 좌석 현황 (librsv.korea.ac.kr)
├── timetable.py   # 수업시간표 + ICS export
├── courses.py     # 개설과목 검색, 강의계획서 (infodepot.korea.ac.kr)
├── grades.py      # 전체 성적 / 누적 GPA / 취득학점
└── lms.py         # Canvas LMS 연동 (mylms.korea.ac.kr, KSSO SAML)

기술 스택

영역	기술	설명
MCP	FastMCP (mcp[cli])	Claude Code 연동 프로토콜
HTTP	httpx (async)	비동기 HTTP 클라이언트
파싱	BeautifulSoup4 + lxml	HTML 스크래핑
포털 인증	KUPID SSO	동적 폼 필드 + ssotoken 추출
LMS 인증	KSSO SAML SSO	SAML IdP 로그인 + RSA 복호화
암호화	cryptography	Canvas 임시 비밀번호 RSA 복호화
도서관	HODI REST API	librsv.korea.ac.kr (인증 불필요)
개설과목	infodepot	SSO token handoff 방식 세션 연동
LMS API	Canvas REST API	mylms.korea.ac.kr 세션 쿠키 인증

트러블슈팅

MCP 서버가 연결되지 않을 때

1. 서버가 정상 동작하는지 확인:

   ku-portal-mcp --version
   

2. 서버가 등록되어 있는지 확인:

   claude mcp list
   

   목록에 ku-portal이 없으면 설치 > 1. MCP 서버 등록을 참고하세요.

3. Claude Code 재시작 후 /mcp 명령으로 서버 상태 확인

MCP 서버가 목록에 보이지 않을 때

Claude Code는 MCP 서버 설정을 ~/.claude.json에서 읽습니다. ~/.claude/settings.json의 mcpServers에 넣으면 인식되지 않습니다.

반드시 claude mcp add 명령으로 등록하세요:

claude mcp add -s user \
  -e KU_PORTAL_ID=your-id \
  -e KU_PORTAL_PW=your-pw \
  ku-portal \
  uvx ku-portal-mcp@latest

서버 시작 시 타임아웃이 발생할 때

서버 초기화에 수 초가 걸릴 수 있습니다. 기본 타임아웃이 짧아 연결 실패가 발생하면, ~/.claude/settings.json의 env에 타임아웃을 늘려주세요:

{
  "env": {
    "MCP_TIMEOUT": "30000"
  }
}

환경변수 관련

• claude mcp add 시 -e 옵션으로 환경변수를 설정합니다
• 이미 등록된 서버의 환경변수를 변경하려면 claude mcp remove ku-portal 후 다시 추가하세요

라이선스

MIT