ku-portal-mcp

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

"공지사항 보여줘", "도서관 빈자리 있어?", "이번 주 과제 뭐 있어?" 같은 자연어로 포털과 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 목록

인증 안내: 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 서버가 연결되지 않을 때

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