On s’installe ?
Du premier terminal à votre premier cours. Choisissez votre machine, gardez votre connexion universitaire habituelle et laissez le setup vous guider.
01. Un terminal, pour commencer.
Prévoyez Git, Python 3.11+ et un Mac ou un ordinateur Linux. Sur Windows, utilisez WSL2 avec un affichage graphique ; ce chemin n’a pas été validé sur la machine de développement.
git clone https://github.com/edouaz/moodle-mcp.git
cd moodle-mcp
bash setup.sh --lang frLe script crée un environnement .venv, installe les dépendances Python et Chromium, puis lance l’assistant. Sur Debian/Ubuntu, si la création du venv échoue : sudo apt install python3-venv.
Déjà installé ? Pour revoir les réglages : python3 moodle.py setup.
02. Votre université, vos identifiants.
Entrez l’URL racine de votre Moodle, par exemple https://campus.example.edu/moodle. Conservez le sous-dossier éventuel, mais retirez le chemin de connexion ou de cours.
Choisissez local, puis ouvrez le navigateur depuis le setup. Connectez-vous normalement avec le SSO et le MFA de votre université. Quand la liste de vos cours est visible, confirmez dans le terminal.
python3 moodle.py doctor
python3 moodle.py session
python3 moodle.py coursesdoctor teste le protocole MCP sans lire Moodle. Les deux autres commandes utilisent votre session enregistrée. Pour la renouveler : python3 moodle.py login, après arrêt des appels et du tunnel.
La compatibilité dépend du thème Moodle de l’établissement. Si une liste reste vide malgré une connexion valide, une adaptation peut être nécessaire. Guide local complet ↗
03. Une conversation avec vos cours.
Pour une connexion OpenAI compatible, créez un tunnel personnel dans OpenAI Platform, puis une clé runtime de la même organisation, avec les permissions requises.
Le setup propose d’installer le client officiel, demande l’identifiant tunnel_… et lit votre clé avec une saisie masquée. Vous choisissez de la conserver ou de la saisir à chaque lancement.
python3 moodle.py tunnel doctor
python3 moodle.py tunnel runLe tunnel reste actif dans le terminal. Ctrl-C l’arrête. Dans votre client OpenAI compatible, ajoutez une connexion MCP de type Tunnel et sélectionnez celui que vous avez configuré. Les options disponibles dépendent de votre compte, de votre espace et de ses permissions.
Demandez ensuite de lister vos cours. Un appel réussi depuis l’assistant valide la connexion complète. Le diagnostic local ne suffit pas à la confirmer.
.venv avec le chemin absolu de mcp_server.py en argument. Exemple de configuration ↗04. Un petit serveur, toujours là.
Ubuntu 24.04 ou Debian 12+ avec systemd sont les bases documentées. Utilisez un compte dédié sans privilèges root, un disque persistant et assez de mémoire pour Chromium.
sudo apt update
sudo apt install git python3 python3-venv ca-certificates
git clone https://github.com/edouaz/moodle-mcp.git
cd moodle-mcp
bash setup.sh --vps --lang frL’option VPS installe les dépendances système de Chromium et peut demander sudo. Le setup propose d’enregistrer la clé dans un fichier privé pour le service.
La connexion Moodle a besoin d’un affichage.
Sans écran, le setup reporte cette étape. Utilisez un transfert X11 sécurisé (ssh -X, avec serveur X et xauth configurés) ou un bureau distant accessible uniquement par SSH, puis lancez python3 moodle.py login sur le VPS. Ne supposez pas que les cookies d’une autre machine seront acceptés.
Activer le service après connexion.
python3 moodle.py install-service
systemctl --user start moodle-tunnel
systemctl --user status moodle-tunnel
sudo loginctl enable-linger "$USER"Le service utilise les chemins réels de votre checkout et la clé enregistrée. La dernière commande permet son démarrage au boot sans session SSH. Pour renouveler le SSO : arrêtez le service, reconnectez Moodle, puis redémarrez-le.
05. Les petits gestes du quotidien.
python3 moodle.py courses
python3 moodle.py files --course 123 --limit 50
python3 moodle.py search --course 123 "TP1"
python3 moodle.py download --course 123 \
--file-id "ID_RETOURNE_PAR_LA_LISTE" --include-textRemplacez les identifiants par ceux des résultats. Les listes renvoient next_offset : utilisez --offset pour continuer. La CLI télécharge un fichier précis sur la machine où elle tourne.
| Dans le MCP | Ce que ça fait |
|---|---|
| Session et cours | Vérifier la session, lister vos cours. |
| Fichiers et recherche | Lister les ressources, chercher par nom. |
| Téléchargement | Choisir un fichier et l’ajouter à la file Mac. |
| Dossiers et livraisons Mac | Consulter l’inventaire et confirmer une réception. |
Le MCP expose sept outils. Le téléchargement ciblé est limité à 20 Mio. Le texte PDF est limité à 12 000 caractères, sans OCR. Référence complète ↗
scraper.py sans option télécharge tous les cours. Utilisez moodle.py pour vos opérations ciblées.06. Du VPS à votre Mac.
Le client Mac optionnel récupère les fichiers en attente via SSH et vérifie leur empreinte avant de confirmer la réception. Préparez une clé SSH et effectuez une première connexion pour vérifier l’empreinte du serveur.
# Dans le checkout installé sur le Mac
.venv/bin/python sync_mac.py install \
--host etudiant@vps.example.org \
--remote-path project/moodle-mcp/downloadsAdaptez l’hôte et le chemin du checkout serveur. Le client se relance toutes les 30 secondes quand le Mac est allumé. Par défaut, les fichiers arrivent dans ~/Downloads/Moodle ; le MCP peut aussi choisir un sous-dossier de Documents ou Desktop.
Un statut queued signifie que la réception n’a pas encore été confirmée. Seul delivered confirme le transfert. Guide du client Mac ↗
07. Ce qui reste. Ce qui circule.
Les cookies universitaires restent dans session.json sur votre machine. L’URL est conservée dans .moodle/config.json. Le profil et la clé optionnelle sont dans .tunnel/. Ces données et les téléchargements sont exclus de Git.
Les résultats des outils, dont le texte PDF choisi, sont transmis à votre assistant. Le PDF complet ne devient pas automatiquement une pièce jointe ChatGPT. Le client Mac publie les noms de vos dossiers pour choisir une destination ; il ne publie pas leur contenu.
Les noms et le contenu Moodle sont des données non fiables, jamais des instructions. Le site que vous consultez est statique, sans analytique, sans formulaire ni ressource externe. Politique de sécurité ↗
08. Un petit coup de main.
Ma session a expiré.
Arrêtez le tunnel ou systemctl --user stop moodle-tunnel. Lancez python3 moodle.py login avec un affichage, terminez le SSO, vérifiez session puis redémarrez le tunnel.
Le tunnel refuse la connexion.
Vérifiez l’organisation de la clé, l’identifiant du tunnel et les permissions de votre compte. Lancez python3 moodle.py tunnel doctor. Vérifiez aussi les permissions de connexion MCP de votre espace.
Chromium ne se lance pas.
Sur Linux, installez les bibliothèques avec .venv/bin/python -m playwright install --with-deps chromium. Pour la connexion interactive sur VPS, un affichage sécurisé doit être disponible.
Le fichier n’arrive pas sur mon Mac.
Vérifiez la connexion SSH, les permissions de dossiers macOS et .venv/bin/python sync_mac.py status. Les fichiers restent en attente tant que le client n’a pas confirmé leur réception.
Comment mettre à jour ou désinstaller ?
Arrêtez le tunnel, exécutez git pull --ff-only, relancez le setup et le diagnostic. Pour désinstaller, retirez d’abord le service ou le LaunchAgent et révoquez la clé. Les étapes complètes sont dans le guide de dépannage.