Skip to main content
Glama

Linky — MCP NexAura

Ton agent lit la consommation électrique de la maison (ou du local) du client, chez Enedis, grâce au compteur Linky. Lecture seule, rien d'autre.

Fabriqué par NexAura, publié sous licence MIT.

Ce qu'il fait

Chaque outil se déclare en lecture seule (readOnlyHint).

Quatre outils, que l'agent choisit tout seul selon la question :

Outil

Il répond à…

conso_veille

« Combien j'ai consommé hier ? » (en kWh)

conso_periode

« Et la semaine dernière, jour par jour ? » (entre deux dates, avec total et moyenne)

courbe_charge

« À quelle heure ça consomme ? » (toutes les 30 minutes, 7 jours au plus)

puissance_max

« Mon abonnement est-il trop grand ? » (puissance la plus forte de chaque jour, en VA)

Related MCP server: cledara-mcp

Ce qu'il lit

La consommation du compteur du client, via Conso API (un service gratuit qui passe par l'accès officiel d'Enedis). Les données d'un jour arrivent le lendemain vers 8 h : l'agent ne peut donc pas voir aujourd'hui, seulement jusqu'à hier. La courbe toutes les 30 minutes ne marche que si le client a activé « enregistrement de la courbe de charge » dans son espace Enedis.

Ce qu'il ne fait jamais

  • Il n'écrit rien, ne modifie rien, ne commande rien (pas de réglage du compteur, pas de changement de contrat).

  • Il n'envoie aucune donnée ailleurs que chez Conso API.

  • Il ne montre ni le jeton ni le numéro du compteur, ni à l'agent, ni dans le journal.

  • Il ne redemande pas deux fois les mêmes données (mémoire de 6 h), pour respecter les règles de Conso API (5 demandes par seconde, 10 000 par heure, partagées entre tous les utilisateurs).

Ce qu'il faut au client

  1. Un compteur Linky avec la collecte activée dans son espace Enedis.

  2. Un jeton Conso API, obtenu sur https://conso.boris.sh après avoir donné son accord chez Enedis (le jeton est personnel ; l'accord se retire à tout moment chez Enedis).

  3. Le numéro du compteur (PRM), 14 chiffres, visible dans l'espace Enedis ou sur une facture.

Installer

Le paquet accepte Python 3.10 ou plus ; le verrou est ciblé et contrôlé pour Python 3.11 à 3.13.

git clone https://github.com/Nexauraholding/mcp-linky.git
cd mcp-linky
python3 -m venv .venv && .venv/bin/pip install --require-hashes -r requirements.lock && .venv/bin/pip install --no-deps --no-build-isolation .

Verrou des dépendances

Version 0.1.2 : les dépendances d'exécution, directes et transitives, sont figées avec leurs empreintes SHA-256 dans requirements.lock. Le verrou inclut aussi setuptools et wheel, décrits dans requirements-build.in. Seules les roues binaires sont acceptées : aucune compilation de dépendance ne peut télécharger d'autres outils.

L'option --no-deps empêche la résolution des dépendances du paquet local ; --no-build-isolation empêche pip de télécharger des outils de construction dans un environnement séparé. Les deux sont nécessaires. Après le clonage, choisir le commit approuvé avant d'exécuter ces commandes ; ne pas installer depuis une branche mouvante. Le verrou protège les téléchargements, pas l'authenticité du dépôt ou du commit choisi.

Pour régénérer depuis ce dossier avec l'outil libre uv (version utilisée : 0.12.13) :

uv pip compile pyproject.toml requirements-build.in --universal --generate-hashes --python-version 3.11 --only-binary=:all: --emit-build-options -o requirements.lock

Cette commande conserve les versions déjà verrouillées. Pour les mettre à jour volontairement, ajouter --upgrade, reporter les versions directes avec == dans pyproject.toml, puis régénérer et vérifier le changement. Examiner les différences avant de publier le nouveau commit.

Le verrou est résolu avec les marqueurs de plateforme et de version Python. Les empreintes ont été comparées aux fichiers publiés sur PyPI : toutes les empreintes de chaque version sont présentes, y compris les roues compatibles CPython 3.11, 3.12 et 3.13 sur Linux x86_64 (glibc, manylinux jusqu'à 2.28) et macOS arm64 (macOS 14). Ce contrôle des fichiers ne remplace pas une exécution sur ces machines. Alpine/musl, Windows et les autres architectures ne sont pas validés.

Le verrou couvre l'installation standard (stdio), sans activer les extras http ou test. Les bibliothèques que mcp exige lui-même restent incluses, même si elles peuvent aussi servir au mode HTTP. Les commandes d'extras ci-dessous nécessitent un verrou distinct ; elles ne bénéficient pas du verrou standard.

Brancher dans Hermès

Dans config.yaml de l'agent :

mcp_servers:
  linky:
    command: /chemin/vers/mcp-linky/.venv/bin/python
    args: ["-m", "nexaura_linky"]
    env:
      LINKY_TOKEN: "le-jeton-conso-api"
      LINKY_PRM: "12345678901234"
      LINKY_MCP_JOURNAL: "/chemin/vers/journal/linky.jsonl"   # facultatif
    tools:
      include: [conso_veille, conso_periode, courbe_charge, puissance_max]

tools.include est facultatif (les quatre outils sont déjà les seuls) ; il sert à retirer un outil, par exemple courbe_charge, sans toucher au code.

Brancher en http, avec un mandat (OAuth 2.1)

Le mode stdio ci-dessus reste le branchement local, sans jeton : c'est ce qu'Hermès fait aujourd'hui. Quand le MCP tourne sur un serveur, il devient une ressource protégée OAuth 2.1, selon la spécification d'autorisation MCP (version courante 2026-07-28) :

  • il publie ses métadonnées de ressource protégée (RFC 9728) : /.well-known/oauth-protected-resource/mcp pour une ressource en /mcp ; une réponse 401 y renvoie le client ;

  • il n'accepte qu'un jeton émis pour lui (audience = son adresse exacte, RFC 8707), signé, non expiré ;

  • la seule portée est linky:read : aucune portée d'écriture n'existe. Un jeton qui n'a que linky:write ou qonto:read reçoit 403 ;

  • le client mène le flux standard (code d'autorisation + PKCE + paramètre resource) : c'est le travail du client MCP, pas du nôtre.

Le mandat

Le mandat est ce jeton court (15 minutes au plus), émis par le serveur d'autorisation selon le flux standard, à partir de l'accord que l'humain a donné. Il dit :

Dans le jeton

Sens

sub

pour qui l'agent agit (l'humain qui a donné son accord)

client_id

quel agent agit (le client OAuth)

scope

sur quoi : linky:read

aud

quel MCP : le sien, et aucun autre

mandat.perimetre

le périmètre : outils (liste d'outils permis), depuis (première date lisible, AAAA-MM-JJ)

mandat.jusqu_a

jusqu'à quand (secondes Unix) : le mandat fini est refusé même si le jeton vit encore

mandat.id

l'identifiant du mandat, écrit dans chaque ligne du journal

Pas d'échange de jetons (RFC 8693) : la spécification MCP de base ne l'emploie pas, et Hermès sait déjà faire le flux standard (voir ci-dessous). (Changement du 27 oct. : la première version prévoyait cet échange.)

Le jeton est refusé (401) s'il est expiré, mal signé, d'un autre émetteur, pour une autre audience, de type autre que at+jwt, plus long que 15 minutes, ou sans mandat, sans agent, sans date de fin ; le mandat fini est refusé de même. Chaque refus est noté au journal (raison courte, jamais le jeton).

Lancer

.venv/bin/pip install ".[http]"
LINKY_MCP_TRANSPORT=http \
LINKY_MCP_ISSUER=https://auth.exemple.fr/realms/nexaura \
LINKY_MCP_RESOURCE=https://linky.exemple.fr/mcp \
LINKY_TOKEN=... LINKY_PRM=... \
.venv/bin/python -m nexaura_linky

Le serveur écoute en local (127.0.0.1:8791) : mets devant lui un proxy en https, et donne l'adresse publique dans LINKY_MCP_HOTES. Un LINKY_MCP_RESOURCE en http n'est accepté que sur la machine locale.

Côté Hermès : rien de maison

Hermès sait déjà faire OAuth 2.1 avec PKCE vers un MCP en http (auth: oauth, voir la documentation MCP d'Hermès) : découverte, identification du client (CIMD, sinon enregistrement dynamique), jeton, renouvellement.

mcp_servers:
  linky:
    url: "https://linky.exemple.fr/mcp"
    auth: oauth
    oauth:
      scope: "linky:read"

Quel serveur d'autorisation ?

Aucun n'est écrit ici : on prend une brique libre. Trois ont été regardés (sources officielles, 27 oct.) :

Keycloak (26.2 et plus)

oidc-provider (panva, Node)

Authlib (Python)

Nature

produit complet, écran d'accord, comptes, journal

bibliothèque certifiée OpenID

boîte à outils

Code + PKCE, jeton JWT (RFC 9068)

oui

oui

oui (9068 listé)

resource (RFC 8707)

non géré (dit dans sa doc) : l'audience se règle par la portée

oui, natif

non listé

Login, accord, comptes

déjà là

à écrire

à écrire

Keycloak évite d'écrire un serveur d'autorisation (écran d'accord, comptes et journal des connexions existent). Ses limites : pas de paramètre resource (on lie l'audience à la portée linky:read par un mappeur d'audience), et pas de fin automatique d'un accord (le mandat jusqu_a et le périmètre viennent d'attributs posés au moment de l'accord). Si ces limites gênent, oidc-provider est le repli.

Les tests utilisent un faux serveur d'autorisation (tests/faux_as.py), qui fait le flux standard.

Le journal

Chaque appel ajoute une ligne dans un fichier local (par défaut ~/.nexaura/journal/linky.jsonl, réglable avec LINKY_MCP_JOURNAL). Une ligne = un appel, lisible par un humain :

{"quand": "2026-10-28T07:31:02+00:00", "service": "linky", "outil": "conso_periode", "parametres": {"debut": "2026-10-20", "fin": "2026-10-26"}, "acces": "lecture", "duree_ms": 412, "resultat": "ok"}

En mode http, la ligne porte aussi mandat (l'identifiant), pour et agent ; en stdio, mandat vaut null. Un appel hors périmètre, ou un jeton refusé, s'écrit resultat: refuse.

En cas d'erreur, resultat vaut erreur et un court texte l'explique. Jamais de jeton ni de PRM : même dans les messages d'erreur, ils sont remplacés par ***.

Les accès dans un fichier privé

Copie secrets.exemple dans un dossier privé, par exemple ~/.nexaura/acces/linky.env, puis protège-le avec chmod 600 ~/.nexaura/acces/linky.env avant d'y mettre tes vrais accès. Le fichier doit t'appartenir et être un fichier ordinaire, sans lien symbolique. Ne le mets jamais dans Git.

Dans le bloc env de la configuration ci-dessus, remplace les accès par ce chemin :

      LINKY_SECRETS_FILE: "~/.nexaura/acces/linky.env"

Écris une ligne CLE=valeur par accès. Les lignes vides et les commentaires commençant par # sont ignorés ; les espaces autour des clés et valeurs et les guillemets simples ou doubles autour des valeurs sont retirés. Seules les clés LINKY_TOKEN et LINKY_PRM sont lues. Une variable déjà présente dans l'environnement garde la priorité, même vide. Si un accès obligatoire manque et que le fichier est absent ou vide, l'erreur indique son chemin.

Variables

Variable

Rôle

LINKY_SECRETS_FILE

Chemin du fichier privé des accès (facultatif, ~ accepté).

LINKY_TOKEN

jeton Conso API (obligatoire)

LINKY_PRM

numéro du compteur, 14 chiffres (obligatoire)

LINKY_MCP_JOURNAL

emplacement du journal (facultatif)

LINKY_BASE_URL

autre adresse d'API, pour les tests (facultatif)

LINKY_MCP_TRANSPORT

stdio (défaut) ou http

LINKY_MCP_ISSUER, LINKY_MCP_RESOURCE

http : serveur d'autorisation, adresse publique de ce MCP (obligatoires)

LINKY_MCP_JWKS_URL

http : adresse des clés publiques (sinon trouvée par RFC 8414)

LINKY_MCP_HOST, LINKY_MCP_PORT, LINKY_MCP_HOTES

http : écoute (127.0.0.1:8791) et noms d'hôte publics

Tests

uv pip compile pyproject.toml --extra test --constraint requirements.lock --generate-hashes -o /tmp/linky-tests.lock
.venv/bin/pip install --require-hashes -r /tmp/linky-tests.lock
MCP_TEST_SANS_RESEAU=1 .venv/bin/python -m pytest -q

En mode strict MCP_TEST_SANS_RESEAU=1, aucun socket n'est autorisé et les tests qui ouvrent une fausse API locale ou un faux serveur d'autorisation sont ignorés. Sans cette variable, ces serveurs locaux sont utilisés, sans appel à Enedis ni à un serveur d'autorisation réel.

Vérification 0.1.2 (27 octobre 2026), copies et environnements neufs hors du dépôt, macOS arm64 : installation avec empreintes, construction locale sans réseau et pip check réussis sous Python 3.11.15 et 3.14.6. python -m pytest -q en mode strict : 38 réussis, 26 ignorés, pour chacun. Python 3.12/3.13 et Linux n'ont pas été exécutés ; leurs roues et empreintes ont été contrôlées.

Licence

MIT (voir LICENSE). Les formats de réponse viennent de la documentation publique de Conso API ; aucun code de bokub/linky (GPL-3.0) n'est repris.

Available Tools

4 tools
conso_periodeA

Donne la consommation d'électricité jour par jour, en kWh, entre deux dates incluses, avec le total et la moyenne. Dates au format AAAA-MM-JJ (exemple 2026-05-01). Jusqu'à 366 jours, jusqu'à hier au plus tard. Lecture seule.

Inputs: fin (required), debut (required).

conso_veilleA

Dit combien d'électricité le foyer a consommé hier, en kWh (kilowattheures). À utiliser pour « combien j'ai consommé hier ? ». Lecture seule.

Inputs: no named parameters.

courbe_chargeA

Donne la consommation toutes les 30 minutes (puissance moyenne en watts et énergie en kWh). Sans dates : hier. 7 jours au plus. Dates au format AAAA-MM-JJ, incluses. Marche seulement si le client a activé l'enregistrement de la courbe de charge chez Enedis. Lecture seule.

Inputs: fin, debut.

puissance_maxA

Donne la puissance maximale atteinte chaque jour (en VA) et le jour le plus fort de la période. Utile pour savoir si l'abonnement est trop petit ou trop grand. Sans dates : hier. Dates au format AAAA-MM-JJ, incluses. Lecture seule.

Inputs: fin, debut.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 4 tools

    Disambiguation4/5

    The four tools target distinct query types: yesterday's total, a date-range daily series, a 30-minute load curve, and daily maximum power. The only overlap is that conso_veille is effectively a one-day convenience subset of conso_periode, but the descriptions clearly steer usage.

    Naming Consistency4/5

    All tool names use French noun phrases in snake_case (conso_veille, conso_periode, courbe_charge, puissance_max), which is consistent and readable. They do not follow a verb_noun pattern, but that is reasonable for a read-only server.

    Tool Count5/5

    Four tools is well-scoped for a Linky consumption reader: each provides a distinct view of consumption or power. No tool feels redundant or unnecessary.

    Completeness4/5

    The surface covers core consumption use cases: yesterday's total, date-range daily totals, load curve detail, and maximum power. Minor gaps exist, such as no explicit today/real-time query or cost/aggregate insights, but agents can work around them.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      Provides read-only access to a Ryde account so agents can pull completed rides and GPS routes, owned and available RidePasses, payments, city fare rules, and ride summaries or pass-cost comparisons. Requires an SMS-authenticated login and never modifies account data.
      20
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables read-only lookup and analysis of SaaS applications, transactions, invoices, spend, renewals, and people, including spend summaries, upcoming renewals, and missing-invoice checks, through an MCP client.
      7
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables users to search and retrieve French company identities, establishments, officers and BODACC notices, normalize and geocode addresses, and get legal-notice requirements, regulated rates, next steps, and prepare drafts through a keyless read-only MCP server.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to inspect and manage customer-service consultations through MCP tools, including reading conversations and, after explicit confirmation, replying, assigning managers, and updating status. Write actions are disabled and contact details masked by default.
      144 npm
      MIT