# Moodle Study MCP

An [MCP](https://modelcontextprotocol.io) server that lets Claude read your ETH
Moodle courses so it can plan your exam prep. Ask Claude things like:

> "For Control Systems II, exam in 12 days — how many lectures, problem sets,
> quizzes and practice exams do I have, and what should I actually do?"

The server fetches, counts, and categorizes your course content. Claude does the
reasoning. Works for any Moodle site (defaults to ETH; set `MOODLE_URL` for others).

## What it gives Claude

| Tool | What it does |
|------|--------------|
| `list_courses` | Your enrolled courses |
| `get_course_overview` | Detected counts (lectures / problem sets / practice exams / quizzes) + the raw item list |
| `sync_course` | Downloads + text-extracts all materials into a local cache |
| `list_quizzes` | Every quiz + how many attempts you've made |
| `search_materials` | Full-text search across everything you've synced |
| `get_material` | The extracted text of one file, for Claude to read |

## Setup (ETH students)

Requires Python 3.10+.

```bash
git clone <this-repo> && cd Moodle-MCP
pip install -e .
```

### 1. Get your token (once)

ETH uses SSO, so you need a Moodle **web-service token** (a 32-character hex
string). The token is stored in your OS keyring (never in a file, never in git)
and is long-lived.

```bash
python -m moodle_mcp auth
```

This opens a browser; log in with SSO. At the end Moodle tries to hand the token
back via a `moodlemobile://token=...` redirect. Since no app is registered for
the `moodlemobile://` scheme, your browser shows an error — **"address invalid"**
(or *"Safari cannot open the page because the address is invalid"*). **That's
expected.** You just need to fish the `token=...` value out of that failed
redirect and paste it at the prompt.

Most browsers (Safari and Chrome included) **hide** the failed URL, so grab it
from DevTools instead:

- **Safari** — enable **Settings → Advanced → "Show features for web
  developers"**, then **Develop → Show Web Inspector** (`⌥⌘I`) → **Network** tab.
  Run the login, click the **`launch.php`** entry → **Response**, and search for
  `moodlemobile://token=`. Copy that whole value.
- **Chrome / Edge** — `Ctrl/⌘+Shift+I` → **Network** tab → run the login → open
  the **`launch.php`** response and find `token=`.

Paste that value at the `Paste the moodlemobile://token=... value here:` prompt
(the tool decodes it for you).

> **Non-ETH Moodle sites:** many expose the token directly under your profile →
> **Preferences → Security keys** (`<your-moodle>/user/managetoken.php`), listed
> as **"Moodle mobile web service"**. If it's there, skip the browser dance:
> `python -m moodle_mcp auth --token <token>`. Note: the **RSS** token on that
> page is *not* the right one, and ETH does not list the mobile token there.

Verify:

```bash
python -m moodle_mcp doctor
```

### 2. Register with Claude Code

```bash
claude mcp add moodle -- python -m moodle_mcp serve
```

Then in Claude: *"List my Moodle courses"*, or *"Give me a study overview of
Fluid Dynamics."*

## Other universities

```bash
export MOODLE_URL="https://moodle.your-uni.example"
python -m moodle_mcp auth
```

The classifier keywords (`taxonomy.yaml`) are tuned for German + English ETH
naming. Add your own patterns there if your course names differ.

## Privacy & security

- Your token is a password to your Moodle account. It lives only in your OS
  keyring. `.gitignore` excludes the cache and any token files.
- The local cache (`~/.moodle-mcp/`) holds copyrighted course material — it stays
  on your machine.
- Uses only Moodle's sanctioned mobile web-service API. No scraping.

## Development

```bash
pip install -e ".[dev]"
pytest
```