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 runs headless off that until it expires.

auth.json and .env.local hold secrets. Both 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.json

Tools

Tool	Args	Returns
list_courses	—	Course names + ou IDs
get_announcements	courseId	Announcements (title, body, date, attachments)
get_content	courseId	Content modules/topics with URLs
get_topic_file	courseId, topicId, pages?	Lecture PDF/PPTX rendered as one image per slide (cap 25; pages like "4" or "2-6")
get_grades	courseId	Grade items (grade, points, weight, feedback)
get_assignments	courseId	Assignments with due dates, instructions, your submission status + files, released feedback
get_upcoming	courseId, daysAhead?	Due dates / events (default 30 days)

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 (ChatGPT or Claude.ai)

ChatGPT and Claude.ai are cloud-hosted — they reach your server remotely over HTTPS, unlike Claude Desktop (local). This exposes one URL over Tailscale Funnel (free, no VPS, stable URL) that both apps share:

npm run setup:web       # builds, enables Funnel, prints your connector URL + per-app steps
npm run autostart:web   # optional: keep server running across reboots

It prints a URL like https://<device>.ts.net/mcp/<secret>. Add it as a custom connector with No Auth (neither app has an API-key field, so the secret rides in the path):

• ChatGPT → Settings → Connectors → Developer mode → Add custom connector → Server URL.
• Claude.ai → Settings → Connectors → "+" → name + URL (no Developer mode needed).

Details: skills/connect-web-chat/SKILL.md. (setup:chatgpt / autostart:chatgpt still work as aliases.)

The full URL is the password — anyone with it can read your LEARN data. Your laptop must be awake with the server running for the chat app to reach it.

After a reboot (web chat path)

setup:web is one-time. The connector URL, secret, Funnel config, and auth.json all persist. Only the server process stops on reboot:

• Ran autostart:web → nothing to do; it restarts itself on login.
• Didn't → npm run start:http to bring the server back. (No need to re-run setup.)

Tailscale must be running for Funnel to work (the macOS app auto-starts on login by default).

Notes

• list_courses uses the enrollments API, falling back to homepage scraping. Other tools call D2L's REST API through the authenticated session.
• get_topic_file returns slides as images so the model can read diagrams, not just text. PDFs need nothing extra; PowerPoint topics additionally need LibreOffice (brew install --cask libreoffice) for the PPTX→PDF step. Works in Claude (Desktop + Claude.ai) and ChatGPT.
• "No valid LEARN session" (or tools failing after weeks) = session expired → npm run login again. Independent of reboots.
• Override with env vars: LEARN_BASE_URL, LEARN_AUTH_FILE, PORT, LEARN_MCP_TOKEN.

---

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.