waterloo-learn-mcp
This MCP server provides read-only access to your University of Waterloo LEARN account and an optional Google Drive folder. Key capabilities:
List courses: Retrieve enrolled courses with IDs.
View announcements: Read instructor announcements with dates and attachments.
Browse course content: Navigate modules, topics, files, and links as a nested table of contents.
Inspect lecture files: Render PDF or PowerPoint slides as images, specifying pages/slides (e.g.,
"4","2-6").Check grades: View grade items, scores, weights, and feedback.
Manage assignments: See due dates, instructions, attachments, submission status, and feedback.
Track upcoming deadlines: Get calendar events and due dates for assignments, quizzes, exams (configurable look-ahead).
Access course outline: Fetch the full syllabus with grading scheme and schedule.
Search Google Drive: If configured, search for past assessments (quizzes, tests, exams) by keyword.
Inspect Drive files: Render Drive-based PDFs, PowerPoints, Google Docs/Slides as images.
Provides tools for searching and retrieving files from a configured Google Drive folder, including past exams and quizzes, using the Google Drive API.
Allows rendering Google Slides presentation files as page images, so AI models can read their content visually.
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., "@waterloo-learn-mcp What's due this week in my CS 246 course?"
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.
waterloo-learn-mcp
Read-only local MCP server for University of Waterloo LEARN courses, slides, deadlines, grades, assignments, announcements, and course outlines.
It uses STDIO: ChatGPT desktop or Codex starts the Node process locally and talks to it through pipes. There is no public URL, tunnel, open port, MCP OAuth or token, Developer mode, or manually created plugin.
Connect to ChatGPT desktop (Windows)
1. Install the requirements
ChatGPT desktop, signed in
Node.js 20 or newer
Git
Confirm Node and Codex are available in PowerShell:
node --version
codex --version2. Download and set up the server
git clone https://github.com/LargoLardo/waterloo_learn_mcp.git
cd waterloo_learn_mcp
npm run setupA browser opens. Sign in to LEARN with WatIAM, approve Duo, and wait for the
terminal to print Setup complete. Setup installs dependencies, builds the
server, saves the LEARN session to ignored auth.json, and registers the local
MCP in the configuration shared by ChatGPT desktop and Codex.
At the start of every study session: run
npm run loginand complete WatIAM and Duo. The command refreshesauth.jsonand also repairs a missing Codex MCP registration. Running MCP processes detect refreshed authentication on the next tool call. If registration had to be repaired, the command tells you to restart ChatGPT/Codex once so it can load the restored server.
3. Enable and test it in ChatGPT desktop
Fully quit ChatGPT desktop, including its Windows system-tray process, then reopen it.
Start a new chat and type
/mcp. You can also check Settings > MCP servers; some app versions show the list under Plugins.Confirm
waterloo-learn-mcpis present and enabled.Auth unsupportedis normal for a local STDIO server.Ask: “List my Waterloo LEARN courses.”
Do not enable Developer mode or use Plugins > + to create a connection. That flow is for remote HTTPS MCP servers; this server is registered locally.
PDF slides work immediately. PowerPoint and Word files require LibreOffice:
winget install TheDocumentFoundation.LibreOfficeManual registration
If automatic setup reaches the login step but the MCP does not appear, run:
npm install
npx playwright install chromium
npm run build
npm run register
codex mcp listThen fully restart ChatGPT desktop once to load the MCP registration. Later
npm run login refreshes the running MCP and verifies that its registration is
still present. It restores a missing entry without first deleting healthy MCP
configuration.
Run npm run login separately whenever the saved WatIAM/Duo session needs to
be refreshed; it performs the same registration check after saving the session.
Related MCP server: Canvas MCP Server
Authentication
There are two separate connections:
ChatGPT → MCP: local STDIO pipes. No OAuth or bearer token is needed, so the UI may report
Auth unsupported.MCP → LEARN: authenticated HTTPS using the WatIAM/Duo browser session in
auth.json.
auth.json is never returned as MCP output. Requested course data is returned
to ChatGPT so it can answer you.
Tools
Tool | Purpose |
| List enrolled courses and IDs |
| Gather exam announcements, events, syllabus, lesson files, and past assessments by course code/name or ID |
| Search up to 60 course files and return relevant passages with file/page references |
| Read announcements and attachments |
| Browse modules, topics, files, and links |
| Return selected PDF/PowerPoint/Word pages as text and images |
| Read grades, weights, and feedback |
| Read assignments, submissions, and feedback |
| Read upcoming events and due dates |
| Read the official course outline/syllabus |
| Search an optional configured Drive folder |
| Return an allowed Drive file as page text and images |
All tools are read-only. Slide tools accept pages such as "4", "2-6", or
"2,4,7-9" and return up to 30 page images per call.
For exam preparation, call get_exam_context with a course such as "CS 135"
and an optional assessment such as "midterm 2" (default: "final exam"). It
gathers the available sources in one call and reports warnings for missing
sources, including optional Google Drive access.
Then use search_course_materials with subject concepts from the exam scope.
It indexes 40 files by default (maxFiles can be raised to 60) and caches
extracted text locally for 24 hours. Results include file/page references and
calls to get_topic_file for inspecting diagrams. Set refresh: true to
redownload files before the cache expires. Scanned pages without a text layer
still need visual inspection; this search does not perform OCR.
Optional configuration
Copy .env.local.example to .env.local only if you want login autofill,
custom cache paths, or Google Drive search. .env.local is ignored by Git.
LEARN_MATERIAL_CACHE_DIR overrides the extracted-text cache directory, which
defaults to ignored cache/materials/. Treat it as private course material.
For Drive search, enable the Google Drive API and set either
GOOGLE_DRIVE_API_KEY for a public/shared folder or a short-lived
GOOGLE_DRIVE_ACCESS_TOKEN with the drive.readonly scope. Limit searchable
folders with GOOGLE_DRIVE_FOLDER_IDS.
GitHub safety
Never commit auth.json, .env.local, or cache/. They are ignored, but check
before pushing:
git diff --cached
git ls-files auth.json .env.local "cache/**"The second command must print nothing.
Development
npm test
npm run buildDisclaimer
This unofficial project is not affiliated with the University of Waterloo or D2L. Use it only with your account, respect university policies and course copyright, and verify important grades, deadlines, and policies in LEARN.
Available Tools
10 toolsget_announcementsGet AnnouncementsA
Get announcements/news posted by instructors for a course. Returns title, body, posted date, and attachments. Use to answer: "Any new announcements?", "What did the professor post?"
Inputs: courseId (required). Returns: announcements
get_assignmentsGet AssignmentsA
Get assignments (dropbox folders) for a course: due date, instructions, attached problem sheets, your submission status (submitted/unsubmitted), submitted files, and released feedback/score. Use to answer: "Have I submitted Assignment 5?", "What is still due?", "What feedback did I get?"
Inputs: courseId (required). Returns: assignments
get_contentGet Course ContentA
List the content modules and materials (lectures, slides, files, links) for a course as a nested table of contents. Use this as the primary source for course activity questions like "what did we do today?", "what was in today's tutorial/lab/lecture?", "what is this week's work?", "what materials are in week 3?", or "where are the lecture slides?". After identifying relevant topics, call get_topic_file to inspect PDFs or PowerPoints.
Inputs: courseId (required). Returns: modules
get_course_outlineGet Course OutlineA
Fetch the official syllabus and return its full text. Use to answer: "What is the grading scheme?", "How much is the midterm worth?", "What is the late policy?", Use this tool WHENEVER user asks about content with chronological language,like "today", "this week", etc.Outlines have a week-by-week schedule, ALWAYS use it to orient chronologically — then call get_content & get_topic_file to pull matching lecture materials. If no outline link exists, check get_content
Inputs: courseId (required). Returns: url, text, title
get_drive_fileGet Google Drive File as Page ImagesA
Download and inspect a file returned by search_drive_files. PDFs, PowerPoints, Google Docs, and Google Slides are rendered as readable page images. Access is restricted to files inside the configured Drive folder.
Inputs: fileId (required), pages. Returns: note, pages, filename, totalPages
get_gradesGet GradesA
Get your grades for a course: each grade item with displayed grade, points, weight, and feedback. Use to answer: "What are my grades?", "How did I do on the midterm?"
Inputs: courseId (required). Returns: grades
get_topic_fileGet Topic File as Slide ImagesA
Download a lecture file (PDF or PowerPoint) from course content and return each page/slide as an image you can read — including diagrams and figures. topicId is the id of a topic from get_content. Slide N = page N; pass pages like "4" or "2-6" to fetch specific slides instead of the whole deck. Use after get_content to answer: "Summarize lesson 2", "What is the diagram on slide 4?"
Inputs: topicId (required), courseId (required), pages. Returns: note, pages, filename, totalPages
get_upcomingGet Upcoming Due DatesA
Get upcoming calendar events and due dates (assignments, quizzes, exams) for a course. Use to answer: "What is due this week?", "When is the next deadline?", or "what work is due today?". This does not list lecture/tutorial materials; pair it with get_content for "what did we do today/this week?"
Inputs: courseId (required), daysAhead. Returns: events
list_coursesList CoursesA
List the courses you are enrolled in on Waterloo LEARN. Returns course names and their ou (org unit) IDs, which the other tools take as courseId. Use to answer: "What courses am I taking?"
Inputs: no named parameters. Returns: courses
search_drive_filesSearch Past Assessments in Google DriveA
Recursively search the configured Google Drive folder for relevant past quizzes, tests, midterms, exams, practice material, and solutions. Search by course code and useful terms, for example "CS 135 quiz" or "MATH 136 midterm". With no query, returns assessment-like files. Use get_drive_file to inspect a result.
Inputs: limit, query. Returns: files, query, folderIds, indexedFiles
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool targets a distinct resource: courses, announcements, content, files, grades, assignments, upcoming events, outlines, and drive files. Slight overlap exists between get_content, get_course_outline, and get_upcoming, but their descriptions clarify different intents (materials vs. schedule vs. deadlines).
All tools follow a consistent verb_noun pattern: list_courses, get_announcements, get_content, get_topic_file, get_grades, get_assignments, get_upcoming, get_course_outline, search_drive_files, get_drive_file. The verbs (list, get, search) are used appropriately and predictably.
10 tools is well-scoped for an LMS integration. Each tool earns its place, covering course discovery, content access, assessment tracking, and file retrieval without unnecessary redundancy or bloat.
The set covers core user workflows: listing courses, reading announcements, browsing content, inspecting files, checking grades, tracking assignments, seeing upcoming deadlines, retrieving the outline, and searching Drive for practice material. Minor gaps exist (e.g., no discussion board tool or assignment submission), but these are not central to the server's stated purpose.
Maintenance
Related MCP Connectors
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
Read-only MCP server for RZ AI Labs — query its services, workshops, and contact info.
MCP server for Argo RPG Platform — connects AI assistants to campaign data via OAuth2
MCP server for RiverScript, an AI transcription platform - fetches transcripts shared via a link.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server that gives desktop AI apps access to your Waterloo LEARN courses, enabling listing courses, getting announcements, content, grades, and upcoming events through natural language.52ISC
- AlicenseNot gradedqualityDmaintenanceMCP server that provides tools to read UBC Canvas LMS data, including courses, assignments, announcements, submissions, and calendar, for use with Claude Desktop, Claude Code, or n8n AI agents.11 npmMIT
- AlicenseNot gradedqualityDmaintenanceA powerful Model Context Protocol (MCP) server that seamlessly integrates AI assistants with Moodle Learning Management System. Enable your AI assistant to access courses, retrieve educational content, download resources, and search through your learning materials.30 npm1MIT
- AlicenseNot gradedqualityBmaintenanceAn MCP server that connects AI assistants to university D2L Brightspace and Piazza, enabling query of courses, grades, assignments, deadlines, files, and Piazza posts.7MIT