Skip to main content
Glama
riadh-mnasri

ecoledirecte-mcp

by riadh-mnasri
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
TypeScript
Local

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: Smartschool MCP Server

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

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

Outil

Description

lister_eleves

Liste les élèves rattachés au compte

consulter_notes

Notes d'un élève (studentId)

consulter_devoirs

Cahier de texte d'un élève (studentId)

consulter_absences

Absences, retards, sanctions d'un élève (studentId)

consulter_messages

Messages reçus dans la messagerie du compte

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

Available Tools

5 tools
consulter_absencesA

Récupère les absences, retards et sanctions d'un élève.

ParametersJSON Schema
NameRequiredDescriptionDefault
studentIdYesIdentifiant EcoleDirecte de l'élève (voir lister_eleves)

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The verb 'Récupère' implies a read-only operation, but with no annotations and no mention of authorization, scope limits, or possible side effects, there is limited behavioral transparency. The description adds some value by signaling the read-only nature, but does not go further.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that states the verb, object, and scope without any filler. Ideal conciseness for an agent to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple single-parameter lookup, the description provides enough context: it specifies the data type and target. It does not mention return format or whether filtering is applied, but the tool's simplicity makes the description sufficiently complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The only parameter, studentId, is fully documented in the schema with a description referencing lister_eleves. The tool description itself adds no additional meaning beyond what the schema already provides, so a baseline score is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Récupère') and names the exact resource ('absences, retards et sanctions'), clearly distinguishing it from sibling tools like consulter_notes or consulter_devoirs. No ambiguity about what the tool returns.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description makes the usage context clear: retrieve disciplinary/tracking data for a student. It does not explicitly name alternatives or exclusions, but the scope is specific enough that an agent can infer when to use it versus the sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

consulter_devoirsA

Récupère le cahier de texte (devoirs à faire) d'un élève.

ParametersJSON Schema
NameRequiredDescriptionDefault
studentIdYesIdentifiant EcoleDirecte de l'élève (voir lister_eleves)

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description carries the full burden of disclosing behavior. It clearly implies a read operation via 'récupère', but it does not mention output shape, possible side effects, auth requirements, or date scoping. It is adequate but thin.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no filler. The action and object are stated immediately, and the parenthetical 'devoirs à faire' clarifies scope without extra words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple lookup tool with one well-documented parameter, the description gives enough context for an agent to choose and call it. It does not mention what fields are returned or whether assignments are date-filtered, but the tool's complexity is low enough that these are not critical gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter is fully documented in the schema ('Identifiant EcoleDirecte de l'élève'), and the description reinforces that the homework belongs to one student. Since schema coverage is 100%, the description does not need to add much, but it also adds little beyond what the schema already states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description is precise: it uses a specific verb ('récupère') and an explicit object ('le cahier de texte (devoirs à faire) d'un élève'). This makes the tool's purpose immediately distinguishable from sibling tools like consulter_notes or consulter_absences.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the intended use—retrieving a student's homework—but does not explicitly contrast it with alternatives or state exclusions (e.g., not for past assignments). Sibling tool names help, but the description itself does not provide selection guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

consulter_messagesA

Récupère les messages reçus dans la messagerie EcoleDirecte du compte.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The verb 'Récupère' signals a read-only retrieval operation and the word 'reçus' narrows the scope, which is useful. However, with no annotations provided, the description carries the full burden and does not disclose potential side effects, authentication needs, or return shape.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single focused sentence with a front-loaded verb and object. Every word contributes to identifying the resource and scope, with no filler or redundant detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the zero-parameter schema and simple read action, the description is adequate for selecting and invoking the tool. However, there is no output schema and no mention of what fields the returned messages contain, so the description is not fully complete for downstream use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the baseline is 4. The description adds useful context about the data source (EcoleDirecte messaging), but there are no parameters to document or clarify further.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb, 'Récupère', and names a clear resource: 'les messages reçus dans la messagerie EcoleDirecte du compte'. It also distinguishes itself from siblings like consulter_notes, consulter_devoirs, and consulter_absences by targeting the messaging channel rather than grades or homework.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly implies when to use the tool: whenever the agent needs to retrieve received EcoleDirecte messages. It does not explicitly name alternatives or state exclusions, so it stops short of a 5, but the context is clear enough for an agent to select this tool over its siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

consulter_notesB

Récupère les notes d'un élève.

ParametersJSON Schema
NameRequiredDescriptionDefault
studentIdYesIdentifiant EcoleDirecte de l'élève (voir lister_eleves)

TDQS

B3.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses the core read behavior ("Récupère") and the target resource, which is adequate for a simple retrieval. However, with no annotations present, it does not describe output format, error behavior, or access requirements, leaving meaningful gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no wasted words. It could be slightly more informative, but it is efficient and directly states the core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter read tool, the description plus schema covers the main invocation path. However, there is no output schema and no description of the returned shape or limits, so completeness is adequate but not thorough.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the parameter is already documented in the schema. The tool description itself adds no parameter-level meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ("Récupère") and a precise resource ("les notes d'un élève"), clearly identifying both the action and the object. It also distinguishes the tool from siblings such as consulter_devoirs and consulter_absences by resource type.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no guidance about when to use this tool versus the sibling tools, nor does it state any exclusion conditions. The only indication is the resource name itself, which is implicit rather than explicit routing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

lister_elevesA

Liste les élèves rattachés au compte EcoleDirecte connecté.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The word 'Liste' implies a read-only listing operation ante the account scope clarifies which data is used. However, with no annotations, the description carries the full burden and does not explicitly state side effects, return behavior, or output shape.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single clear sentence with no redundant or misleading content. Its key scoping information is front-loaded and immediately usable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter list tool, the description is logically complete: it names the action, the object, and the source account. A slightly more explicit statement of read-only behavior would make it fully self-contained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters to document, so the schema itself adds little. The description adds useful meaning by specifying that the students are those attached to the connected EcoleDirecte account.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the operation ('Liste') and the target resource ('élèves'), scoped to the connected EcoleDirecte account. This is specific enough to distinguish it from sibling tools that handle consults or other resources.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided about when to choose this tool over siblings or when not to use it. The intended use case must be inferred from the word 'élèves' rather than stated explicitly.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 5 tool updatesv0.1.0
    • First observedconsulter_absences
    • First observedconsulter_devoirs
    • First observedconsulter_messages
    • First observedconsulter_notes
    • First observedlister_eleves
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.9/5.0

Scored across 5 tools

Disambiguation5/5

Each tool targets a clearly distinct resource: students, grades, homework, absences, and messages. No two tools could plausibly be confused for one another.

Naming Consistency4/5

All names follow a verb_noun pattern in snake_case, but one tool uses 'lister' while the rest use 'consulter', even though they all perform retrieval. This is a minor inconsistency that does not seriously impair use.

Tool Count5/5

Five tools is well-scoped for a small school-data access server. Each tool covers a meaningful and distinct resource without unnecessary bloat.

Completeness4/5

The core read-only domain is well covered: students, grades, homework, absences/sanctions, and messages. Missing operations like timetable retrieval or sending messages are likely outside the server's stated read-only scope, so they are minor gaps at most.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers