Awesome Monash Tools

Agent-native MCP servers for Monash University — Ed, Moodle, Gmail and OnTrack, exposed as 22 read-only tools your agent can call.

English · 中文

Monash students work across four systems that never talk to each other: Ed for discussion, Moodle for deadlines and materials, Gmail for official mail, OnTrack for FIT task feedback. None of them offers a student-facing API. This repository turns all four into small, typed, read-only MCP tools so an agent can answer "what is due, what did my tutor say, and what did I miss?" with real data instead of guesses.

Unofficial. Not affiliated with Monash University, Ed, Moodle, Google or Doubtfire. Use your own account, at your own risk, and respect each service's terms.

🤖 Built for agents, not for humans

This repository ships no app, no dashboard and no chat UI. The only interface is a set of MCP tools. Every design choice targets the model on the other side of the protocol:

Works with any MCP host: Claude Code, Claude Desktop, Cursor, Codex, DeepSeek Harness, or your own agent loop.

Related MCP server: induslms-academics

📋 Table of Contents

• Why this exists

• What's inside

• What agents can do

• Quick start

• MCP configuration

• Tool catalogue

• Design principles

• Security and privacy

• Repository layout

• Development

• Contributing

• Related projects

• License

💡 Why this exists

Ask a Monash student a simple question — "what's due this week?" — and the real answer requires four logins, four UIs and a mental join. The information exists, but it is optimized for humans clicking around, not for an agent answering.

Existing tools stop halfway:

• moodle-cli, edstem-cli and ontrack-cli are excellent terminal tools. They print tables for a person and assume a person runs them.

• Scraping libraries return HTML. A model then burns context re-reading a Moodle theme.

• Each service authenticates differently (API token, SSO cookie, OAuth, refresh cookie). Doing that per question is impossible.

This project does the boring part once — authentication, normalization, and error recovery — and exposes the result as 22 MCP tools with consistent shapes. The agent does the thinking; the repository does the plumbing.

What this is not: not a Monash client, not a notification app, not a scraper you point at arbitrary URLs, and not a way to automate submissions. There is deliberately no write access.

📦 What's inside

🎯 What agents can do

Real questions, and the tools that answer them:

Because everything is scoped to your own account, the answers are yours: your submissions, your feedback, your inbox. Nothing is shared or cached remotely.

🚀 Quick start

Requires Node.js 20.11+ and Google Chrome (only for the two SSO logins).

# Until the npm release lands, install from source (30 seconds):
git clone https://github.com/jackdsjk/awesome-monash-tools.git
cd awesome-monash-tools
npm install
npm run build
npm link                     # exposes the `awesome-monash` command

# Connect the sources you actually use.
awesome-monash login ed
awesome-monash login moodle
awesome-monash login ontrack
awesome-monash login gmail --client-id <id> --client-secret <secret>

# See what is connected.
awesome-monash status

# Start a server.
awesome-monash serve all

login moodle and login ontrack open a Chrome window: finish the normal Monash SSO login, wait for the dashboard, and the session is saved automatically. Nothing is typed into this tool.

After the npm release: npx -y awesome-monash-tools@latest <command> works identically.

🔌 MCP configuration

Claude Code

claude mcp add monash -- awesome-monash serve all

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json)

{
  "mcpServers": {
    "monash": {
      "command": "awesome-monash",
      "args": ["serve", "all"]
    }
  }
}

Prefer one server per source (smaller tool list, clearer permissions):

{
  "mcpServers": {
    "ed":       { "command": "awesome-monash", "args": ["serve", "ed"] },
    "moodle":   { "command": "awesome-monash", "args": ["serve", "moodle"] },
    "gmail":    { "command": "awesome-monash", "args": ["serve", "gmail"] },
    "ontrack":  { "command": "awesome-monash", "args": ["serve", "ontrack"] }
  }
}

Cursor uses the same JSON in .cursor/mcp.json.

Codex (~/.codex/config.toml):

[mcp_servers.monash]
command = "awesome-monash"
args = ["serve", "all"]

🧰 Tool catalogue

Full parameters and return shapes: docs/tools.md.

Ed — discussion threads and lessons

Moodle — deadlines and materials

Gmail — the official inbox

OnTrack — FIT task feedback

🧱 Design principles

1. Normalize at the edge. Moodle is scraped internally and returned as structured sections — the model never sees HTML.

2. One job per tool. moodle_deadlines does deadlines; moodle_submission_status checks one submission. No mega-tools.

3. Verb + noun names, prefixed by source. ed_get_thread is unambiguous in a 22-tool list.

4. Fail with the fix. Every AmtError carries a hint; the tool result includes the exact command to run.

5. Read-only by construction. No write code path exists. ontrack_download writes a local file and is the only non-read-only annotation.

6. Stable shapes. Field names, ISO timestamps, deterministic ordering — agents can rely on them between calls.

7. Local and quiet. stdio transport, no server component, no analytics, no remote cache.

🔒 Security and privacy

• Credentials live in ~/.config/awesome-monash-tools/credentials.json, mode 0600; AMT_CONFIG_DIR relocates them.

• No password is ever entered into this tool. Moodle and OnTrack logins happen in a real Chrome window.

• Gmail requests only gmail.readonly; revoke at https://myaccount.google.com/permissions.

• No telemetry, no remote logging, no third-party service in the middle.

• Output is sensitive by definition (grades, feedback, email). Treat transcripts accordingly.

• Environment overrides exist for advanced users: ED_API_TOKEN, MOODLE_COOKIE, ONTRACK_REFRESH_TOKEN, GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET.

🗂 Repository layout

src/core/       config, credential store, HTTP retries, MCP helpers
src/ed/         Ed client, tools, server bin
src/moodle/     Moodle client (AJAX + scraping), tools, server bin
src/gmail/      Gmail client + OAuth loopback, tools, server bin
src/ontrack/    OnTrack client (refresh-cookie auth), tools, server bin
src/all.ts      combined server
src/cli.ts      login / logout / status / serve
docs/           auth guide and tool reference (EN + 中文)
scripts/        protocol-level smoke test

🛠 Development

npm install
npm run check     # tsc --noEmit + vitest
npm run build     # emit dist/
npm run smoke     # start every server over stdio and call one tool
npm run dev -- status

The test suite uses a fake fetch; no real account is required to develop. See AGENTS.md for conventions.

🤝 Contributing

• New tools: keep them read-only, add a zod schema, annotate with readOnlyHint, and make the error hint actionable.

• New sources: follow src/ed/ (client → tools → server) and add a credential section in docs/auth.md.

• Docs: update both README.md and README.zh-CN.md, and both language versions of docs/.

• Run npm run check && npm run smoke before opening a PR.

🌏 Related projects

Other community work in the Monash × agents space. Some of it taught this project how the APIs behave; none of it is bundled here.

Built something else for Monash students? Open a PR and add it to the table.

📄 License

MIT © 2026 jackdsjk

Built for agents that need to know what is due.