EcoleDirecte MCP

Serveur MCP qui permet à Claude de lire les données d'un compte EcoleDirecte (notes, devoirs, absences, messages) directement en conversation, sans passer par le site.

Un modèle à copier, pas un service

Ce projet n'est pas un service auquel tu te connectes : c'est un programme que chaque famille installe et fait tourner chez elle, avec ses propres identifiants EcoleDirecte. Aucun serveur central, aucune base de données, personne d'autre que toi ne voit jamais ton identifiant ou ton mot de passe : ils restent dans un fichier .env sur ta machine.

Concrètement, ça veut dire :

• Pas de compte à créer, pas d'inscription

• Pas de responsabilité de stockage de données d'autrui, de RGPD ou de sécurité côté "fournisseur" : il n'y a pas de fournisseur, juste un outil que tu copies

• Si tu veux l'adapter, l'améliorer ou le comprendre, le code est fait pour ça (voir "Architecture" plus bas)

C'est un point de départ technique à réutiliser pour ta propre famille, pas un produit à laquelle t'abonner.

Related MCP server: unofficial-magister-mcp

Important : API non officielle

EcoleDirecte n'expose aucune API publique documentée. Ce serveur s'appuie sur l'API interne du site (api.ecoledirecte.com). Conséquences concrètes :

• Le format des réponses peut changer sans préavis. Chaque endpoint est validé par un schéma (zod) : en cas de changement, l'outil renvoie une erreur explicite plutôt que des données silencieusement fausses.

• En cas d'échec du live, chaque outil retombe automatiquement sur le dernier résultat mis en cache (dossier .cache/, jamais commité) en signalant qu'il s'agit de données potentiellement périmées.

• Ce serveur est une couche de confort, pas le seul accès aux données : en cas de panne, se reconnecter manuellement sur ecoledirecte.com reste toujours possible.

Ce qui a été vérifié par capture réseau réelle (2026-09-10)

• login.awp : structure des comptes/élèves (data.accounts[].profile.eleves[])

• notes.awp : moyennes par matière et par période (data.periodes[].ensembleMatieres.disciplines[]), sans note individuelle par évaluation observée cette année (aucune note encore saisie au moment du test)

• cahierdetexte.awp (liste) + cahierdetexte/{date}.awp (détail, contenu encodé en base64/HTML) pour les devoirs

• URL et paramètres de viescolaire.awp (absences/retards) et familles/{id}/messages.awp (messages)

• Version d'API réelle : 4.101.4

Le login exige une poignée de main GTK

login.awp refuse silencieusement des identifiants pourtant valides (Identifiant et/ou mot de passe invalide !) si l'appel ne reproduit pas exactement le protocole attendu :

1. GET /v3/login.awp?gtk=1&v=<version> renvoie deux Set-Cookie, dont un nommé GTK=....

2. Le POST de login doit inclure le header X-Gtk avec cette valeur et renvoyer les cookies reçus à l'étape 1 dans un header Cookie classique — sans ce header Cookie, l'API répond code: 200 côté navigateur mais rejette l'appel côté serveur pour la même requête, avec le même message trompeur qu'un mauvais mot de passe.

ensureLoggedIn() dans src/infrastructure/ecoledirecte-client.ts fait les deux. Si ce comportement disparaît après une évolution de l'API, revérifier ce flow avant de soupçonner les identifiants.

Ce qui reste à vérifier

• La forme exacte du corps de réponse de viescolaire.awp et de messages.awp (URLs confirmées, schémas encore best-effort) : ces deux outils peuvent échouer au premier usage réel, il faudra alors ajuster src/infrastructure/ecoledirecte-client.ts.

• La forme des notes individuelles (par évaluation) une fois que des notes seront saisies dans le trimestre en cours.

Stack

• Node.js + TypeScript, exécuté en local uniquement (pas de serveur HTTP, pas de déploiement)

• @modelcontextprotocol/sdk, transport stdio

• zod pour la validation des réponses API

• vitest pour les tests

Installation rapide

npx ecoledirecte-mcp-init

Un assistant en ligne de commande demande l'identifiant et le mot de passe EcoleDirecte et écrit ~/.ecoledirecte-mcp/.env (en dehors du dossier du projet, pour que ça reste stable même installé via npx).

Installation manuelle (développement)

npm install
npm run build
node dist/cli/init.js

.env.example documente les deux variables attendues (ECOLEDIRECTE_USERNAME, ECOLEDIRECTE_PASSWORD) si tu préfères écrire ~/.ecoledirecte-mcp/.env à la main. Ce fichier ne doit jamais être commité dans le projet lui-même.

Premier login et double authentification

Au premier login depuis un appareil non reconnu, EcoleDirecte peut demander une question de sécurité. Ce cas est détecté (SecurityChallengeError) et remonté clairement par les outils : dans ce cas, se connecter une fois manuellement sur le site depuis cette machine pour lever le blocage, puis relancer.

Développement

npm run dev    # lance le serveur MCP en stdio (tsx)
npm test       # tests vitest
npm run build  # compilation TypeScript vers dist/

Aucun port réseau : ce n'est pas une application web, le serveur communique uniquement via stdin/stdout.

Connexion à Claude Code

claude mcp add ecoledirecte -- npx -y ecoledirecte-mcp

(en développement local, avant publication npm : claude mcp add ecoledirecte -- node /chemin/vers/ecoledirecte-mcp/dist/index.js)

Connexion à Claude Desktop

Dans la config Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json) :

{
  "mcpServers": {
    "ecoledirecte": {
      "command": "npx",
      "args": ["-y", "ecoledirecte-mcp"]
    }
  }
}

Dans les deux cas, les identifiants sont lus depuis ~/.ecoledirecte-mcp/.env (voir "Installation rapide"), pas besoin de les répéter dans la config.

Outils MCP exposés

Architecture

• src/domain/ : types métier et ports (interfaces), aucune dépendance à l'API EcoleDirecte

• src/infrastructure/ : adapter HTTP EcoleDirecte + cache fichier, seul endroit qui parle le format brut de l'API

• src/mcp/ : exposition des outils MCP, orchestre fetch live + fallback cache

Cette isolation permet de ne corriger que l'adapter le jour où EcoleDirecte change son API, sans toucher aux outils exposés à Claude.

Licence

MIT, voir LICENSE. Copie, adapte, réutilise pour ta propre famille.

© 2026 Riadh MNASRI