LearnUs local MCP server
This server is a local, read-only MCP tool that lets AI clients view Yonsei LearnUs coursework—courses, assignments, schedules, announcements, videos, attendance, and files—without modifying LearnUs.
Course exploration: list enrolled courses (
learnus_list_courses), inspect a course structure (learnus_get_course), and list its activities (learnus_list_activities)Assignments & deadlines: get assignment details and submission/grading status (
learnus_get_assignment) and list calendar events/deadlines in a date range (learnus_upcoming)Announcements & notifications: list announcements (
learnus_list_announcements), read full announcement bodies with attachments (learnus_get_announcement), and view notifications without marking them read (learnus_list_notifications)Video learning & attendance: list course videos (
learnus_list_videos), check video completion/attendance (learnus_get_video_attendance), and summarize required-incomplete/completed/optional learning states (learnus_get_learning_overview)Files & downloads: discover downloadable course materials (
learnus_list_files) and download previously discovered files to a local folder (learnus_download_file)Summaries: get a broad multi-category overview (
learnus_get_overview) or an actionable weekly coursework summary (learnus_get_weekly_tasks)Diagnostics: check the current login/session status (
learnus_auth_status)
Provides tools to interact with Yonsei University's LearnUs, a Moodle-based learning management system, enabling users to view courses, assignments, announcements, video learning status, and download course materials.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@LearnUs local MCP server 이번 주 LearnUs 과제와 마감 일정 알려줘"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 buildLinux에서 브라우저 시스템 의존성도 설치해야 한다면 npx playwright install --with-deps chromium을 사용하세요. TypeScript와 Playwright의 전역 설치는 필요하지 않습니다.
2. MCP 클라이언트에 연결
사용하는 클라이언트의 로컬 MCP 서버 설정에 아래 실행 정보를 등록하세요. 설정 파일의 형식은 클라이언트마다 다릅니다.
설정 | 값 |
서버 이름 |
|
실행 명령 |
|
인자 |
|
환경변수 |
|
인자 경로는 실제 저장소의 절대경로로 바꾸세요. 인증정보는 클라이언트의 환경변수 전달 기능이나 지원되는 비밀정보 관리 기능으로 서버 프로세스에 제공하세요. 서버는 .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를 자동 우선하지 않습니다.
분류 | 도구 | 용도 |
종합 |
| 영상 학습을 포함한 주간 학업 요약 |
종합 |
| 과제·일정·공지 등 선택한 범주의 요약 |
강좌 |
| 수강 강좌 목록 |
강좌 |
| 특정 강좌의 구조와 활동 |
강좌 |
| 강좌별 학습 활동 목록 |
과제·일정 |
| 과제 안내, 마감, 첨부파일과 제출·채점 상태 |
과제·일정 |
| 지정 기간의 일정과 마감 |
공지·알림 |
| 공지 목록 |
공지·알림 |
| 공지 본문과 첨부파일 |
공지·알림 |
| 알림 목록 |
영상 |
| 강좌별 영상 목록 |
영상 |
| 영상별 학습·출석 상태 |
영상 |
| 필수 미완료·완료·선택/제외·불명 상태 요약 |
자료 |
| 강의자료 목록 |
자료 |
| 요청한 파일을 로컬에 다운로드 |
진단 |
| 현재 프로세스의 로그인 상태 확인 |
직접 도구를 호출할 때는 조회 결과의 ID를 사용하세요. courseId·moduleId·articleId·videoId는 양의 정수 문자열, 과제 상세의 cmid는 양의 정수 숫자, fileId는 등록된 UUID입니다. 입력 필드와 선택 옵션은 클라이언트에 노출되는 도구 스키마에서 확인할 수 있습니다.
조회 결과를 읽는 기준
주간 기본 범위는 한국 시간(Asia/Seoul) 월요일~일요일입니다.
overview는 기본적으로 일정·과제·공지를 각각 최대 10개 요약합니다. 강좌·알림·학습 상태는 선택 옵션이며,weekly_tasks는 학습 상태도 포함합니다.공지·알림·새 파일은 정보성 항목입니다. 반드시 해야 할 일로 취급하지 않으며, 대상이나 마감 근거가 부족하면
unknown을 유지합니다.영상의 완료·진도·출석은 구분합니다. Moodle 완료 표시는 다운로드나 실제 독서를 증명하지 않습니다. 일부 조회가 실패하면 경고로 알립니다.
자세한 기준은 주간 조회와 학습 상태 해석을 참고하세요.
설정
환경변수 | 기본값 / 용도 |
| 로그인 인증정보 |
|
|
|
|
|
|
|
|
| 선택 사항; 강좌 ID별 |
|
|
|
|
기능별 캐시는 별도로 유지됩니다. 상세 동작은 캐시·요청 제어를 참고하세요.
보안과 제한
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:inspectorInspector UI는 npm run inspector로 실행합니다. 실계정 검증은 인증정보와 LEARNUS_INTEGRATION=1을 안전하게 전달한 환경에서 npm run test:integration:release로 실행하세요. 다운로드 검증에는 별도 활성화가 필요하며, 일반 CI에는 실계정 인증정보를 설정하지 않습니다.
구조와 검증의 세부 사항은 아래 문서에 정리되어 있습니다.
응답 크기·토큰 평가 —
npm run evaluate:tokens; 실제 LLM 토큰 수나 클라이언트의 도구 선택을 검증하는 측정은 아닙니다.
라이선스
Available Tools
16 toolslearnus_auth_statusARead-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_announcementARead-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_assignmentARead-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_courseARead-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_overviewARead-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_overviewARead-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_attendanceARead-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_tasksARead-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_activitiesARead-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_announcementsARead-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_coursesARead-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_filesARead-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_notificationsARead-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_videosARead-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_upcomingARead-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
Scored across 16 tools
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.
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.
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.
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
Related MCP Connectors
PLATO (Pusan National University LMS) MCP server via Moodle Web Service API + ubboard scraping
Read your plat.plus courses, tasks, course pages, sessions, files and messages. Read-only.
Read and manage courses, members, orders, events, posts, and settings for Loopwise-powered sites.
Unofficial NTNU course data: search, timetables, grades, course info, and exam logistics.
Related MCP Servers
- AlicenseBqualityBmaintenanceEnables 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.192MIT
- AlicenseAqualityAmaintenanceEnables 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.71MIT
- AlicenseBqualityCmaintenanceEnables 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.19MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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