isu-moodle-mcp

Ein MCP-Server, der Moodle an Claude anbindet. In zwei Ebenen aufgeteilt:

• API-Ebene (18 Tools, das Rückgrat): Offizielle Web-Service-REST-API. Kein HTML-Scraping, kein Browser nötig.

• CDP-Ebene (6 Tools, um Lücken zu schließen) + Altsystem-Ebene (4 Tools): Debug-Chrome nur dann, wenn die API wirklich nichts liefert. Das wichtigste Tool ist probe_course_access() – es ist die einzige Möglichkeit herauszufinden, dass es einen Kurs gibt, den du nicht mehr sehen kannst.

Im Alltag reicht die API-Ebene völlig aus. Die CDP-Ebene ist für Fragen wie „Sind alle Kurse, die ich unterrichtet habe, in der Liste?" gedacht.

Für Workshop-Einheit 3 von „KI-Praxis im Kursdesign" der AIEA der I-Shou-Universität (2026-08-21). Einfach herunterladen und an deine eigenen Bedürfnisse anpassen – kein GitHub-Konto nötig.

Was das ist

Das im Unterricht demonstrierte flipclass-mcp ist der MCP-Server für FlipClass der Southern Taiwan University of Science and Technology. Dieses System hat keine API, daher bezieht es seine Daten über zwei Wege: HTML-Scraping (32 XPath-Stellen) + Debug-Chrome (für Seiten wie die Notenmatrix oder Mitgliederlisten, die reines HTTP nicht lesen kann). Das ist die Demonstration von „Egal wie geschlossen das System ist – mit Zugangsdaten kann man es vollständig reverse-engineeren."

Dieses Projekt ist die andere Hälfte derselben Sache: Wenn die Gegenseite eine API hat, kann derselbe MCP-Tool-Vertrag komplett auf ein anderes Backend umgestellt werden.

Tool-Namen und Docstrings sind auf beiden Seiten bewusst identisch gehalten, sodass du direkt vergleichen kannst, wie dasselbe Bedürfnis in „mit API" und „ohne API" jeweils aussieht.

Related MCP server: Moodle MCP Server

Schnellstart

1. Code holen

git clone https://github.com/scatjay/isu-moodle-mcp.git

Ohne Git kannst du auf der GitHub-Seite auch Code → Download ZIP wählen.

2. Abhängigkeiten installieren

pip install -r requirements.txt

Es gibt nur zwei: requests und mcp.

3. Ein Token besorgen

python get_token.py https://moodle.你的學校.edu.tw

Es fragt nach deinen Moodle-Zugangsdaten und schreibt bei Erfolg das Token in .env.

Führe diesen Schritt in deinem eigenen Terminal aus, nicht in einem KI-Chat. Chat-Transkripte können gespeichert oder gesichert werden – sobald Passwort und Token darin auftauchen, sind sie praktisch geleakt.

Warum ein Token und nicht Zugangsdaten? Ein Token kann widerrufen werden, ist an deine eigenen Berechtigungen gebunden und führt nicht wie ein Passwort bei einem Leak zum Totalverlust. Moodle-Tokens laufen standardmäßig nach 12 Wochen ab – wenn ein Tool mitten im Semester plötzlich ausfällt und invalidtoken meldet, einfach dieses Skript erneut ausführen.

4. An Claude anbinden

In die Konfigurationsdatei von Claude Desktop (claude_desktop_config.json) eintragen:

{
  "mcpServers": {
    "moodle": {
      "command": "python",
      "args": ["C:/你的路徑/isu-moodle-mcp/server.py"],
      "env": {
        "MOODLE_URL": "https://moodle.你的學校.edu.tw",
        "MOODLE_TOKEN": "貼上 .env 裡那一串",
        "MOODLE_LEGACY_URL": "https://舊站網址（沒有舊站就整行刪掉）"
      }
    }
  }
}

5. Zuerst den Health-Check ausführen

Nach der Anbindung solltest du Claude als Erstes diagnose() ausführen lassen. Es zeigt dir, ob das Token gültig ist, welche Funktionen du tatsächlich aufrufen kannst und was fehlt. Wenn etwas nicht funktioniert, ist das das erste Tool, das du ausführen solltest.

Verfügbare Tools

CDP-Ebene (zuerst python start_debug_chrome_moodle.py ausführen und dich in diesem Fenster anmelden)

Altsystem-Ebene (wenn die Hochschule die Plattform gewechselt hat)

Dafür muss in .env eine Zeile MOODLE_LEGACY_URL=https://alte-seite.de ergänzt werden.

Diese Version enthält bewusst keinerlei Schreib-Tools (z. B. mod_assign_save_grade zum Ändern von Noten). Bei reinen Leseoperationen ist ein Fehler höchstens falsche Daten; bei Schreiboperationen veränderst du wirklich die Noten von Studenten. Falls du sie wirklich brauchst, füge sie selbst hinzu – aber übe zuerst auf einer Testinstanz.

Bekannte Einschränkungen (bitte diesen Abschnitt vollständig lesen)

🔴 Alte Kurse verschwinden still – aber unter engeren Bedingungen, als du denkst

core_enrol_get_users_courses gibt nur Kurse zurück, für die du aktuell noch eine Einschreibebeziehung hast.

Am 2026-08-20 mit zwei lokalen Moodle-4.1.18-Instanzen getestet, Punkt für Punkt verifiziert:

Diese Tabelle widerlegt eine weit verbreitete Annahme (auch in der vorherigen Version dieser README): „Versteckte oder archivierte alte Kurse verschwinden." Im Test nicht bestätigt. Was einen Kurs wirklich verschwinden lässt, ist nur die letzte Zeile. Das steht hier, weil eine durch Tests widerlegte Behauptung in der Dokumentation schlimmer ist als gar keine – du würdest danach vom Administrator die falschen Dinge verlangen.

Kurs, Studenten und Aufgaben sind weiterhin in der Datenbank vorhanden, nur du siehst sie nicht. Und die API sagt dir nicht „Es gibt einen Kurs, den du nicht mehr siehst" – sie erwähnt ihn einfach nicht.

Führe daher vor Langzeitanalysen zuerst find_hidden_courses() oder probe_course_access(course_id) für einzelne Kurse aus und verlass dich nicht nur auf die Liste von list_history_courses(). Dieses Tool gibt immer ein caveat-Feld zurück, das dich daran erinnert – bitte ignoriere es nicht.

Moodle-Fehler kommen mit HTTP 200

Wenn Moodle einen Fehler zurückgibt, ist der HTTP-Statuscode trotzdem 200; der Fehler steckt im exception-Feld des Bodys. raise_for_status() greift hier überhaupt nicht. Dieser Server behandelt das bereits, aber wenn du selbst Programme gegen Moodle schreibst, denk daran.

accessexception ist schwer zu diagnostizieren

Die offiziell gelisteten Ursachen umfassen sieben oder acht Varianten, und sofern der Administrator das Debugging nicht auf NORMAL oder höher stellt, verrät die Fehlermeldung nicht, welche es ist. Dieser Server übersetzt es in verständliche Sprache und nennt die drei wahrscheinlichsten Ursachen, aber um wirklich sicherzugehen, musst du diagnose() ausführen und sehen, welche Funktionen dein Token tatsächlich enthält.

Du siehst nur deine eigenen Kurse

Das ist eine eingebaute Garantie von Moodle, keine Einschränkung dieses Tools. Das Token erbt vollständig deine eigenen Berechtigungen, und jeder Aufruf führt eine Berechtigungsprüfung auf Kontextebene durch. Das ist gleichzeitig Sicherheitsgarantie und Einschränkung.

Array-Parameter funktionieren nicht mit JSON

Die Moodle-REST-API parst mit PHPs $_POST; Arrays müssen als courseids[0]=5&courseids[1]=7 geschrieben werden. Ein JSON-String wird als einzelner String interpretiert und führt zu invalidparameter. Dieser Server flacht das automatisch ab.

Der Dateidownload-Parameter heißt anders

Der REST-Endpunkt verwendet wstoken, aber webservice/pluginfile.php verwendet token. Das ist der Punkt, der beim Portieren am leichtesten übersehen wird. Außerdem muss der Dienst downloadfiles aktiviert haben.

Wenn get_token.py fehlschlägt

Moodle gibt standardmäßig moodle/webservice:createmobiletoken an alle angemeldeten Benutzer, sodass Lehrende normalerweise ohne Administrator selbst ein Token erstellen können. Aber die Schule kann diesen Standardwert ändern – wenn das passiert ist, merkst du es erst, wenn du tatsächlich ein Token erstellen willst; von außen ist das nicht erkennbar.

Entwicklungsnotizen

Dieses Projekt wurde von flipclass-mcp portiert. Beim Portieren wurde die schmerzhafteste Hälfte entfernt und die wertvollste Hälfte behalten:

• Entfernt (ca. 247 Zeilen): _login, anticsrf-Behandlung, Cookie-Cache, checkMultiLogin für Mehrfachlogins, 32 lxml-XPath-Parser, CDP-Verbindung (Debug-Chrome)

• Behalten: FastMCP-Grundgerüst, Signatur und Docstring jedes @mcp.tool() – das ist der eigentliche Wert, denn das ist der Vertrag, den das LLM sieht

Der Grund dafür: Keines der vorhandenen Python-Pakete für Moodle ist brauchbar: moodlepy ist seit fast zwei Jahren nicht mehr aktualisiert und sperrt die Abhängigkeiten auf attrs<23 (Version von 2022); moodle_api.py ist seit drei Jahren veraltet und nicht auf PyPI; python-moodle wird zwar gepflegt, scraped aber HTML statt ein REST-Client zu sein. Die Moodle-REST-API ist so einfach, dass man sie in einem Dutzend Zeilen schreibt – ein veraltetes Paket einzubinden wäre nur zusätzliche technische Schuld.

Lizenz

MIT. Nimm es und passe es an die Version deiner eigenen Hochschule an – ohne zu fragen.