Skip to main content
Glama

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

Confirm Node and Codex are available in PowerShell:

node --version
codex --version

2. Download and set up the server

git clone https://github.com/LargoLardo/waterloo_learn_mcp.git
cd waterloo_learn_mcp
npm run setup

A 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 login and complete WatIAM and Duo. The command refreshes auth.json and 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

  1. Fully quit ChatGPT desktop, including its Windows system-tray process, then reopen it.

  2. Start a new chat and type /mcp. You can also check Settings > MCP servers; some app versions show the list under Plugins.

  3. Confirm waterloo-learn-mcp is present and enabled. Auth unsupported is normal for a local STDIO server.

  4. 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.LibreOffice

Manual 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 list

Then 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:

  1. ChatGPT → MCP: local STDIO pipes. No OAuth or bearer token is needed, so the UI may report Auth unsupported.

  2. 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_courses

List enrolled courses and IDs

get_exam_context

Gather exam announcements, events, syllabus, lesson files, and past assessments by course code/name or ID

search_course_materials

Search up to 60 course files and return relevant passages with file/page references

get_announcements

Read announcements and attachments

get_content

Browse modules, topics, files, and links

get_topic_file

Return selected PDF/PowerPoint/Word pages as text and images

get_grades

Read grades, weights, and feedback

get_assignments

Read assignments, submissions, and feedback

get_upcoming

Read upcoming events and due dates

get_course_outline

Read the official course outline/syllabus

search_drive_files

Search an optional configured Drive folder

get_drive_file

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 build

Disclaimer

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 tools
get_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

    A4.3/5.0

    Scored across 10 tools

    Disambiguation4/5

    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).

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A 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 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      An MCP server that connects AI assistants to university D2L Brightspace and Piazza, enabling query of courses, grades, assignments, deadlines, files, and Piazza posts.
      7
      MIT