Skip to main content
Glama
LearnUs local MCP server

LearnUs local MCP server

LearnUs MCP

MCP 클라이언트에서 연세대학교 LearnUs의 과제, 일정, 공지, 영상 학습 상태와 강의자료를 조회하는 로컬 서버입니다. 여러 강좌의 정보를 모아 이번 주에 확인할 학업 내용을 정리할 수 있습니다.

TypeScript · 로컬 stdio MCP · LearnUs 읽기 전용

빠른 시작

1. 설치

Node.js 22.19 이상, npm, 로컬 stdio MCP를 지원하는 클라이언트가 필요합니다.

git clone https://github.com/illlilililiililll/LearnUS_MCP.git
cd LearnUS_MCP
npm ci
npx playwright install chromium
npm run build

Linux에서 브라우저 시스템 의존성도 설치해야 한다면 npx playwright install --with-deps chromium을 사용하세요. TypeScript와 Playwright의 전역 설치는 필요하지 않습니다.

2. MCP 클라이언트에 연결

사용하는 클라이언트의 로컬 MCP 서버 설정에 아래 실행 정보를 등록하세요. 설정 파일의 형식은 클라이언트마다 다릅니다.

설정

값

서버 이름

learnus

실행 명령

node

인자

["/absolute/path/LearnUS_MCP/dist/index.js"]

환경변수

LEARNUS_ID, LEARNUS_PASSWORD

인자 경로는 실제 저장소의 절대경로로 바꾸세요. 인증정보는 클라이언트의 환경변수 전달 기능이나 지원되는 비밀정보 관리 기능으로 서버 프로세스에 제공하세요. 서버는 .env를 자동으로 읽지 않습니다.

인증정보를 채팅, Tool 인자, 명령줄 또는 커밋되는 설정에 넣지 마세요. 연결 원칙과 범위는 MCP Host 설정을 참고하세요.

이 서버는 웹 주소로 접속하는 서비스가 아닙니다. MCP 클라이언트가 프로세스를 실행하므로 별도로 npm start를 켜 둘 필요는 없습니다.

3. 첫 질문

연결 후 클라이언트의 도구 목록에 learnus_* 도구가 표시되는지 확인하고, 다음처럼 요청하세요.

  • “LearnUs에서 수강 중인 강좌를 보여줘.”

  • “이번 주 LearnUs 과제와 영상 학습 현황을 정리해 줘.”

  • “이 강좌의 최근 공지와 강의자료 목록을 보여줘.”

조회 도구가 필요할 때 자동으로 로그인합니다. learnus_auth_status를 먼저 호출할 필요는 없습니다. 실제 도구 선택은 클라이언트와 모델에 따라 달라집니다.

Related MCP server: seoultech_c4t

제공 도구

주간 과제·출석·학습 질문에는 learnus_get_weekly_tasks, 여러 범주의 종합 조회에는 learnus_get_overview, 특정 항목에는 개별 도구를 사용합니다. 학업과 무관한 개인 할 일 질문에는 LearnUs를 자동 우선하지 않습니다.

분류

도구

용도

종합

learnus_get_weekly_tasks

영상 학습을 포함한 주간 학업 요약

종합

learnus_get_overview

과제·일정·공지 등 선택한 범주의 요약

강좌

learnus_list_courses

수강 강좌 목록

강좌

learnus_get_course

특정 강좌의 구조와 활동

강좌

learnus_list_activities

강좌별 학습 활동 목록

과제·일정

learnus_get_assignment

과제 안내, 마감, 첨부파일과 제출·채점 상태

과제·일정

learnus_upcoming

지정 기간의 일정과 마감

공지·알림

learnus_list_announcements

공지 목록

공지·알림

learnus_get_announcement

공지 본문과 첨부파일

공지·알림

learnus_list_notifications

알림 목록

영상

learnus_list_videos

강좌별 영상 목록

영상

learnus_get_video_attendance

영상별 학습·출석 상태

영상

learnus_get_learning_overview

필수 미완료·완료·선택/제외·불명 상태 요약

자료

learnus_list_files

강의자료 목록

자료

learnus_download_file

요청한 파일을 로컬에 다운로드

진단

learnus_auth_status

현재 프로세스의 로그인 상태 확인

직접 도구를 호출할 때는 조회 결과의 ID를 사용하세요. courseId·moduleId·articleId·videoId는 양의 정수 문자열, 과제 상세의 cmid는 양의 정수 숫자, fileId는 등록된 UUID입니다. 입력 필드와 선택 옵션은 클라이언트에 노출되는 도구 스키마에서 확인할 수 있습니다.

조회 결과를 읽는 기준

  • 주간 기본 범위는 한국 시간(Asia/Seoul) 월요일~일요일입니다.

  • overview는 기본적으로 일정·과제·공지를 각각 최대 10개 요약합니다. 강좌·알림·학습 상태는 선택 옵션이며, weekly_tasks는 학습 상태도 포함합니다.

  • 공지·알림·새 파일은 정보성 항목입니다. 반드시 해야 할 일로 취급하지 않으며, 대상이나 마감 근거가 부족하면 unknown을 유지합니다.

  • 영상의 완료·진도·출석은 구분합니다. Moodle 완료 표시는 다운로드나 실제 독서를 증명하지 않습니다. 일부 조회가 실패하면 경고로 알립니다.

자세한 기준은 주간 조회와 학습 상태 해석을 참고하세요.

설정

환경변수

기본값 / 용도

LEARNUS_ID / LEARNUS_PASSWORD

로그인 인증정보

LEARNUS_DOWNLOAD_ROOT

~/Documents/LearnUS; 다운로드 폴더

LEARNUS_MAX_DOWNLOAD_BYTES

52428800 (50 MiB); 파일 크기 제한

LEARNUS_MAX_CONCURRENT_REQUESTS

4; 동시 데이터 요청 수, 1~32

LEARNUS_CACHE_ENABLED

1; 0이면 일반 TTL 캐시만 비활성화

LEARNUS_COURSE_CONTEXT_OVERRIDES

선택 사항; 강좌 ID별 audienceTags JSON

LEARNUS_INTEGRATION

0; 실계정 조회 테스트 활성화 여부

LEARNUS_DOWNLOAD_INTEGRATION

0; 다운로드 통합 테스트 추가 활성화 여부

기능별 캐시는 별도로 유지됩니다. 상세 동작은 캐시·요청 제어를 참고하세요.

보안과 제한

Playwright로 실제 SSO 페이지에서 인증하고, 인증된 요청으로 LearnUs 데이터를 조회합니다. 세션과 쿠키는 메모리에 보관하며 CAPTCHA·다중 인증을 우회하지 않습니다.

  • 과제 제출, 퀴즈 시작, 영상 재생·진도 변경, 알림 읽음·삭제는 수행하지 않습니다.

  • 다운로드는 사용자가 요청한 등록 파일만 처리합니다. 지정 폴더에 저장하고 기존 파일을 덮어쓰지 않습니다.

  • ubfile과 과제 첨부파일을 지원합니다. 일부 resource·folder 자료는 FILE_SOURCE_RESEARCH_REQUIRED를 반환할 수 있습니다.

  • 사이트 HTML 변경 시 파서 수정이 필요할 수 있습니다. 시간표의 실제 조회 기능과 원격 MCP 연결은 제공하지 않습니다.

문제가 생기면 보안 및 제한 사항을 확인하세요. 이슈를 남길 때는 인증정보·쿠키·개인 학습자료를 제외하세요.

개발 및 검증

npm run build
npm run lint
npm test
npm run test:browser
npm run test:inspector

Inspector UI는 npm run inspector로 실행합니다. 실계정 검증은 인증정보와 LEARNUS_INTEGRATION=1을 안전하게 전달한 환경에서 npm run test:integration:release로 실행하세요. 다운로드 검증에는 별도 활성화가 필요하며, 일반 CI에는 실계정 인증정보를 설정하지 않습니다.

구조와 검증의 세부 사항은 아래 문서에 정리되어 있습니다.

라이선스

MIT

Available Tools

16 tools
learnus_auth_statusA
Read-onlyIdempotent

Reports whether the current MCP process has an authenticated LearnUs session. Use only when the user explicitly asks whether LearnUs is logged in or whether the session is alive. Do not use it as a prerequisite for a data request; data Tools authenticate automatically and a false status does not imply manual browser login is needed.

Inputs: no named parameters.

learnus_download_fileA

Downloads one previously discovered LearnUs fileId into the configured local LearnUS directory. Use only when the user explicitly asks to download that file. Prefer this Tool over browser download for supported fileIds. It reads remote LearnUs data but creates a local file without overwriting; it does not modify LearnUs. Do not pass URLs or guessed IDs. Browser fallback is allowed only when MCP reports the file/capability unsupported or explicit visual interaction is required.

Inputs: fileId (required).

learnus_get_announcementA
Read-onlyIdempotent

Gets one normalized LearnUs announcement body and registers its attachments as fileIds. Use when the user asks to read a specific announcement already identified by moduleId and articleId. Do not use it to list or search announcements, or to mark a notice read.

Inputs: moduleId (required), articleId (required).

learnus_get_assignmentA
Read-onlyIdempotent

Gets one assignment’s instructions, due date, attachments and submission/grading status by canonical activity cmid. Use when the user asks for details or status of a specific known assignment. Do not use it to search for assignments across courses or to submit/edit an assignment.

Inputs: cmid (required).

learnus_get_courseA
Read-onlyIdempotent

Gets one known LearnUs course with its normalized structure and activities. Use when an exact course is known and the user asks for that course’s contents or structure. Do not use it to discover all enrolled courses or to fetch full assignment/announcement details.

Inputs: courseId (required).

learnus_get_learning_overviewA
Read-onlyIdempotent

Summarizes required incomplete, completed, optional/excluded and unknown VOD learning states. Use when the user asks about course video learning, completion or attendance across a course or week. Do not use it for broad non-video coursework or to treat an unknown target/deadline as a confirmed obligation.

Inputs: week, status, refresh, courseId.

learnus_get_overviewA
Read-onlyIdempotent

Gets a configurable broad LearnUs coursework summary covering assignments, calendar deadlines, announcements, notifications and optional learning/attendance. Use as the default broad LearnUs retrieval Tool when a request spans multiple categories or the exact underlying resource is not yet known, such as what is new, what matters or what is happening across classes. Do not use it solely for generic personal to-do/calendar questions or for a focused request that maps cleanly to a narrower Tool. For weekly actionable coursework specifically, prefer learnus_get_weekly_tasks. Informational, completed and unknown items remain distinct.

Inputs: to, from, courseId, includeCourses, +6 more.

learnus_get_video_attendanceA
Read-onlyIdempotent

Gets canonical completion, viewing progress, attendance target and attendance status for a course or one known video. Use when the user asks whether a specific course video was watched, completed or counted for attendance. Do not use it to play a video or infer attendance from its title.

Inputs: courseId (required), refresh, videoId.

learnus_get_weekly_tasksA
Read-onlyIdempotent

Gets actionable Yonsei LearnUs coursework for the current or requested week: assignments, deadlines, required incomplete learning and attendance items. Use as the default LearnUs Tool when a request clearly concerns Yonsei coursework, classes, assignments, academic deadlines, required lecture videos, incomplete learning or attendance obligations, even without the words LearnUs/런어스. Do not use it for unrelated personal to-do/calendar questions or to treat informational/completed/optional/unknown items as required tasks. Typical requests ask what coursework remains this week, which assignments are due, or whether required videos are incomplete. Calendar entries alone do not prove an unfinished task.

Inputs: to, from, courseId.

learnus_list_activitiesA
Read-onlyIdempotent

Lists assignments, VODs, resources, folders, boards and unknown activity types in one course. Use when the user asks what activities or learning materials exist in a known course, or when a cmid must be discovered. Do not use it for full activity details or cross-course coursework summaries.

Inputs: courseId (required).

learnus_list_announcementsA
Read-onlyIdempotent

Lists normalized LearnUs ubboard announcement summaries, newest dated items first. Use when the user asks for recent course notices or announcements, optionally in one known course. Do not use it for a full announcement body; use learnus_get_announcement with known module/article IDs.

Inputs: limit, courseId.

learnus_list_coursesA
Read-onlyIdempotent

Lists the user’s current LearnUs courses and canonical Moodle course IDs. Use when the user asks which courses/classes they are taking or when another LearnUs Tool needs an exact course ID. Do not use it for activity, assignment or file details inside a known course.

Inputs: no named parameters.

learnus_list_filesA
Read-onlyIdempotent

Discovers safe downloadable course materials, PDFs and attachments and returns opaque fileIds plus Moodle completion state. Use when the user explicitly asks for course files, lecture materials, PDFs, attachments or downloads. Do not use it to download arbitrary URLs or to assume an existing/new file still needs review.

Inputs: courseId (required), scope, refresh.

learnus_list_notificationsA
Read-onlyIdempotent

Lists normalized LearnUs account notifications without marking them read. Use when the user asks about recent LearnUs alerts or notifications. Do not use it to infer a required task merely from a new-file notice; notifications are informational without explicit action evidence.

Inputs: limit.

learnus_list_videosA
Read-onlyIdempotent

Lists VOD activities in one course with canonical IDs, audience applicability and separate availability/instructional deadlines. Use when the user asks what course videos exist or for video metadata in a known course. Do not use it to determine actual attendance/progress status; use learnus_get_video_attendance or learnus_get_learning_overview.

Inputs: courseId (required), refresh.

learnus_upcomingA
Read-onlyIdempotent

Lists canonical LearnUs calendar events and deadlines in a date range, optionally for one course. Use when the user asks for calendar events, schedules or deadlines between specific dates. Do not use it to infer task completion or required attendance; use learnus_get_weekly_tasks for actionable weekly coursework. Date-only values use Asia/Seoul; timestamps require a timezone.

Inputs: to (required), from (required), limit, courseId.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 16 tools

    Disambiguation4/5

    Tools mostly target distinct resource+action pairs (list courses, get assignment, list videos), and descriptions explicitly state when not to use them. However, several summary tools (learnus_get_overview, learnus_get_weekly_tasks, learnus_upcoming) and announcement/notification tools overlap in purpose, requiring careful reading to avoid misselection.

    Naming Consistency4/5

    All tools use the learnus_ prefix and snake_case, with most following a verb_noun pattern (list_, get_, download_). Exceptions like learnus_upcoming and learnus_auth_status are minor deviations from the verb_noun convention. Consistent enough for predictability.

    Tool Count4/5

    16 tools is slightly above the typical 3–15 range but justified by the breadth of LMS resources (courses, activities, assignments, videos, files, notifications, summaries). Each tool appears to serve a specific retrieval granularity, though the set is on the heavy side.

    Completeness4/5

    The surface covers course discovery, activity/assignment details, calendar, announcements, notifications, videos, files with download, and aggregated overviews. Missing grade retrieval or assignment submission, but those may be outside the stated retrieval scope; minor gaps only.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      Enables AI clients to read a student's own UGent Ufora (D2L Brightspace) data, including courses, announcements, deadlines, grades, course materials, and PDF text, over stdio or local Streamable HTTP. All operations are read-only and run locally against the student's authenticated session.
      19
      2
      MIT
    • A
      license
      A
      quality
      A
      maintenance
      Enables AI assistants to query SeoulTech e-Class course announcements and assignments, search full notice text, track pending work, and refresh login sessions securely through natural language.
      7
      1
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables natural-language, read-only access to a user's own learning-management account for courses, assignments and deadlines, lecture attendance, notices, grades, and syllabus evidence, including reading page/slide/cell locations inside PDF, Office, HWP/HWPX, HTML, and ZIP attachments. Runs locally over stdio or remotely over OAuth-protected Streamable HTTP for desktop and mobile clients, and can compare changes against a locally encrypted baseline.
      19
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables users to access and manage course data, assignments, grades, announcements, discussions, pages, modules, and files from their institution's learning management system via terminal commands or MCP-compatible AI agents, including previewing and confirming assignment submissions.
      MIT