waterloo-learn-mcp
This server enables AI applications (Claude Desktop, ChatGPT, Claude.ai) to access your University of Waterloo LEARN (D2L) course data conversationally, using saved browser session cookies to authenticate without repeated logins.
List Courses (
list_courses): Retrieve all enrolled courses with their names and org unit (ou) IDs.Get Announcements (
get_announcements): Fetch instructor-posted announcements for a course, including title, body, posted date, and attachments.Get Course Content (
get_content): Browse a course's full content library — lectures, slides, files, and links — organized as a nested table of contents.Get Topic File: Retrieve lecture slides (PDF/PPTX) rendered as images for the AI to read diagrams.
Get Grades (
get_grades): View grade items with displayed grades, points earned, weight, and instructor feedback.Get Assignments: See assignments with due dates, instructions, submission status, and feedback.
Get Upcoming Due Dates (
get_upcoming): Check upcoming deadlines and calendar events (assignments, quizzes, exams) within a configurable look-ahead period (default 30 days, max 365).Get Course Outline: Retrieve the official syllabus/outline text, cached locally, with fallback to Outline.uwaterloo.ca or LEARN content.
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 Show me my grades for MATH237"
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
MCP server exposing your Waterloo LEARN courses to AI apps. LEARN sits behind WatIAM + Duo, so auth is split out: you log in once in a real browser, the session is saved to auth.json, and the server reuses those cookies over plain HTTP until they expire. (A headless browser is only launched for rare scrape fallbacks, so npx playwright install chromium is still part of setup.)
auth.json, oauth.json, and .env.local hold secrets. They are gitignored — treat them like passwords.
Install
npm install
npx playwright install chromium
npm run build
npm run login # browser opens; sign in + approve Duo. Saves auth.jsonOptional: npm run login can autofill your WatIAM username/password before
waiting for Duo. Add both values to .env.local or export them in your shell:
WATIAM_USERNAME=your-watiam-user
WATIAM_PASSWORD=your-watiam-passwordRelated MCP server: Horizon
Tools
Tool | Args | Returns |
| — | Course names + |
|
| Announcements (title, body, date, attachments) |
|
| Content modules/topics with URLs; |
|
| Adaptive whole-deck contact sheets, or detailed slide images when |
|
| Grade items (grade, points, weight, feedback) |
|
| Assignments with due dates, instructions, your submission status + files, released feedback |
|
| Due dates / events (default 30 days) |
|
| Official course outline/syllabus text from the local cache, refreshing from Outline.uwaterloo.ca when missing |
Connect to Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json, then restart the app:
{
"mcpServers": {
"waterloo-learn": {
"command": "node",
"args": ["/absolute/path/to/waterloo-learn-mcp/dist/index.js"]
}
}
}Local, no tunnel, no exposed session. Details: skills/connect-claude-desktop/SKILL.md.
Connect to a web chat with ngrok
ChatGPT and Claude.ai are cloud-hosted, so they need a public HTTPS URL for this MCP server. The default path is ngrok: the MCP server runs on your laptop, and ngrok publishes it at a stable HTTPS dev domain.
First, install and sign in to ngrok:
brew install ngrok/ngrok/ngrok
ngrok config add-authtoken <your-ngrok-authtoken>Get your free dev domain from the ngrok dashboard, then run the one-time setup:
npm run setup:ngrokWhen prompted, paste the domain only, for example example.ngrok-free.app.
The script saves it to .env.local, starts the local HTTP server, starts ngrok,
and prints your connector URL:
https://<your-ngrok-domain>/mcpUse OAuth. Leave OAuth Client ID and Client Secret blank. When the authorization
page opens, paste the connection code printed by the setup script
(LEARN_MCP_TOKEN from .env.local).
ChatGPT → Settings → Connectors → Developer mode → Add custom connector → Server URL.
Claude.ai → Settings → Connectors → "+" → name + URL.
OAuth clients and tokens are saved in oauth.json so connectors keep working after server restarts.
Treat LEARN_MCP_TOKEN like a password. The legacy URL
https://<your-ngrok-domain>/mcp/<secret> still works for clients that cannot
use OAuth.
After a reboot with ngrok
Your ngrok domain, MCP token, OAuth clients, and LEARN session all persist. After restarting your computer, run:
npm run start:ngrokLeave that terminal running while you want ChatGPT or Claude.ai to reach LEARN.
If the LEARN session expired, start:ngrok exits before starting the tunnel.
You can also check it directly:
npm run check:authTo check the tunnel from another terminal:
curl -s -H 'ngrok-skip-browser-warning: true' https://<your-ngrok-domain>/health
curl -s -H 'ngrok-skip-browser-warning: true' https://<your-ngrok-domain>/.well-known/oauth-authorization-serverExpected:
/health->okOAuth metadata -> JSON with a
registration_endpoint
ngrok may show a browser warning during OAuth. Click through once. Command-line
checks can skip it with the ngrok-skip-browser-warning header shown above.
Tailscale alternative
Tailscale Funnel also works if you prefer it. It has a nice reboot story because Funnel persists its tunnel config; only the local HTTP server needs to be running.
npm run setup:tailscale
npm run start:http
npm run autostart:http # optional: start HTTP server on login
npm run stop:http # stop HTTP autostart and free port 8787Use this connector URL:
https://<device>.ts.net/mcpAfter a reboot with Tailscale:
Ran
autostart:http-> nothing to do; it restarts itself on login.Didn't ->
npm run start:httpto bring the server back.
If Claude/ChatGPT cannot fetch OAuth config or cannot connect to
<device>.ts.net:443, reset Tailscale Serve/Funnel:
tailscale funnel reset
tailscale serve reset
tailscale funnel --bg 8787Notes
list_coursesuses the enrollments API, falling back to homepage scraping. Official titles from Outline.uwaterloo.ca are cached incache/outlines/viewer-outlines.jsonand reused when the outline session is expired. Other tools call D2L's REST API through the authenticated session.get_course_outlinereadscache/outlines/first. Cached outlines are checked against the published revision date and automatically refetched when the instructor publishes a new revision. If a course is not cached, it checks Outline.uwaterloo.ca's enrolled-course viewer, then falls back to outline links posted in LEARN content. If neither exists, look for an uploaded outline/syllabus PDF inget_content.get_content(courseId, query="Week 13 Meeting 1")searches module paths and topic titles before returning data, avoiding a full-semester tool response when only one item is needed. Omitqueryfor the complete hierarchy.get_topic_filereturns native MCP images so the model can read diagrams, not just text. Withoutpages, decks of up to 4 slides return individual PNGs; larger decks return numbered JPEG contact sheets with up to 12 slides each (75-slide overview cap). Passpages="4",pages="2-6", orpages="2,4,7-9"for detailed 800px PNGs (30-slide cap per call).Downloaded PDFs and converted PowerPoints are cached in-process for 15 minutes, up to 100 MB total, so overview-to-detail follow-ups avoid another LEARN download or LibreOffice conversion. PDFs need nothing extra; PowerPoint topics need LibreOffice (
brew install --cask libreoffice). Works in Claude (Desktop + Claude.ai) and ChatGPT."No valid LEARN session" (or tools failing after weeks) = session expired →
npm run loginagain. Independent of reboots.Set
LEARN_SKIP_OUTLINE_REFRESH=1in.env.localto keep startup-triggered logins from opening Outline.uwaterloo.ca or rebuilding the outline cache. Existing cached outlines are still used; live outline lookups can still refresh individual entries when requested.Override with env vars:
LEARN_BASE_URL,LEARN_AUTH_FILE,LEARN_OUTLINE_CACHE_DIR,LEARN_SKIP_OUTLINE_REFRESH,LEARN_TOPIC_FILE_CACHE_TTL_MS,LEARN_TOPIC_FILE_CACHE_MAX_BYTES,PORT,LEARN_MCP_TOKEN,WATIAM_USERNAME,WATIAM_PASSWORD,WATIAM_LOGIN_DOMAIN.
Disclaimer
This is an unofficial, independent tool built for personal academic use. It is not affiliated with, endorsed by, or supported by the University of Waterloo, D2L, or any related entity. "Waterloo LEARN" and related marks belong to their respective owners.
The server acts on your behalf using your own credentials to access only your own course data — it accesses nothing you couldn't already see by logging into LEARN yourself. You are responsible for using it in accordance with the University of Waterloo's acceptable-use policies and LEARN's terms of service. Don't use it to access data that isn't yours, and don't share course content in ways that violate copyright or your instructors' wishes.
LEARN's internal APIs and page structure can change without notice, which may break this tool at any time. It is provided as-is, without warranty of any kind. AI models can also misread or hallucinate content — always verify grades, due dates, and other important information against LEARN directly. Use at your own risk.
Available Tools
5 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).
get_contentGet Course ContentA
List the content modules and materials (lectures, slides, files, links) for a course as a nested table of contents. Use to answer: "What materials are in week 3?", "Where are the lecture slides?"
Inputs: courseId (required).
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).
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?"
Inputs: courseId (required), daysAhead.
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.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool targets a distinct aspect of the LEARN experience (announcements, content, grades, upcoming events, courses), with no overlaps in purpose.
All tool names follow the consistent pattern get_<resource> in snake_case, making them predictable and easy to remember.
5 tools is an ideal size for a student-focused LMS server, covering all essential read operations without unnecessary bloat.
The toolset provides comprehensive coverage of a student's common needs: viewing courses, grades, materials, announcements, and upcoming deadlines. No obvious gaps.
Maintenance
Related MCP Connectors
An MCP server that integrates with Discord to provide AI-powered features.
MCP server for AI dialogue using various LLM models via AceDataCloud
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
An MCP server that gives your AI access to the source code and docs of all public github repos
Related MCP Servers
- AlicenseBqualityDmaintenanceA local MCP server for Canvas LMS that enables querying courses, assignments, grades, modules, and more from any MCP-compatible AI client.12MIT
- 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
- AlicenseNot gradedqualityDmaintenanceMCP server that integrates GitHub, Brightspace, Outlook, and local files, enabling natural language queries for assignments, grades, emails, calendar events, repositories, and file operations.MIT
- AlicenseAqualityCmaintenanceMCP server that lets AI assistants access University of Waterloo LEARN course data (announcements, content, grades, assignments, outlines) and search past assessments in Google Drive.10ISC