Piloter sa box et sa domotique depuis Claude avec un serveur MCP

Chez moi, le réseau tient en trois appareils : une Freebox Ultra, un serveur Home Assistant pour la domotique, et un adaptateur SLZB-MR2 qui porte ses radios Zigbee et Thread. Chacun a sa propre interface d'administration et ses propres identifiants.

Réseau maison les rassemble. Claude peut lire leur état et, sous conditions, agir dessus ; un tableau de bord montre le tout sur une seule page. Rien n'est exposé sur Internet.

Un serveur MCP et un tableau de bord

Le projet a deux entrées. La première est un serveur MCP, le protocole qui permet à Claude d'appeler des outils : j'ouvre une session Claude Code dans le dossier du projet, j'approuve le serveur « maison », et Claude peut demander l'état de la box, la liste des appareils connectés ou le journal d'erreurs de Home Assistant. Le serveur compte dix-neuf outils.

La seconde est un tableau de bord web. Il se lance par un raccourci sur le Bureau, tourne en arrière-plan sans fenêtre de terminal, redémarre seul quand la configuration ou le code changent, et s'arrête avec l'ordinateur.

Les deux passent par les mêmes clients d'API, un par équipement. Une correction faite pour Claude sert aussi au tableau de bord.

Le serveur MCP dialogue avec Claude Code par l'entrée et la sortie standard du programme, sans port réseau. Le tableau de bord n'écoute que sur l'ordinateur lui-même, à l'adresse 127.0.0.1. Il refuse en plus toute requête qui ne vise pas cette adresse ou qui vient d'un autre site : une page web ouverte dans le navigateur ne peut pas s'en servir pour atteindre la maison par un détour.

Ce que Claude a le droit de faire

Les actions possibles sont rangées en trois niveaux.

• Libre : lire l'état des équipements, les appareils connectés, la configuration Wi-Fi sans les clés, les redirections de ports, le DHCP, les entités et les journaux.
• Avec confirmation : créer, activer ou supprimer une redirection de port, réveiller un ordinateur à distance, appeler un service Home Assistant autorisé, régler les LED de l'adaptateur ou le redémarrer.
• Sans outil : redémarrer la box, modifier le Wi-Fi ou le DHCP, mettre à jour un firmware, réinitialiser l'adaptateur. Ces opérations se font dans les interfaces d'origine.

La confirmation repose sur les permissions de Claude Code. Les outils de lecture sont autorisés d'office ; ceux qui agissent passent par une règle « ask », qui me demande mon accord à chaque appel. Ces règles ont une limite, écrite dans la documentation du projet : le mode « bypass » de Claude Code les contourne.

Le troisième niveau ne dépend d'aucun réglage. Aucun outil n'a été écrit pour ces opérations, et le code le dit en tête du serveur : elles passent par les interfaces d'origine.

Un outil qui n'existe pas ne peut pas être appelé, quel que soit le réglage des permissions.

Côté domotique, Claude ne peut appeler que des services de domaines listés un par un : lumières, prises, ventilateurs, volets, chauffage, lecteurs multimédia, scènes, scripts, automatisations, boutons et interrupteurs virtuels. Les serrures, les alarmes et la gestion du réseau Zigbee n'y figurent pas. Le tableau de bord est plus restreint encore : il ne sait qu'allumer et éteindre les lumières, les prises, les ventilateurs et les interrupteurs virtuels.

Faire accepter l'application par la box

La Freebox n'obéit qu'aux applications qu'elle a autorisées. Un script envoie la demande, puis attend : il faut aller devant la box et accepter « Réseau Maison » sur son écran. Le jeton obtenu est rangé dans un dossier de secrets que Git ignore, comme le fichier de configuration qui contient le jeton de Home Assistant.

Ce premier accord ne suffit pas pour les redirections de ports. Il faut ajouter à la main le droit « Modification des réglages » à l'application, dans Freebox OS. Le script le rappelle à la fin de l'appairage s'il manque. La box est interrogée en HTTPS, et le projet vérifie son certificat avec les autorités de certification de la box, rangées dans le projet.

Travailler sans toucher au réseau

Une commande lance le tableau de bord branché sur de faux équipements, qui imitent les réponses de la box, de Home Assistant et de l'adaptateur. On peut ainsi retoucher l'interface sans rien envoyer aux vrais appareils. La capture en tête de ce carnet vient de ce mode.

Parmi les appareils factices, l'un porte un nom piégé : un morceau de code HTML qui s'exécuterait s'il était inséré tel quel dans la page. Le nom d'un appareil connecté est choisi par son propriétaire, donc par n'importe qui sur le Wi-Fi. Le tableau de bord doit l'afficher comme du texte.

Les tests automatiques tournent sur les mêmes faux équipements, pour les clients d'API, le serveur MCP et le tableau de bord.

Les décisions en route

• Pas d'outil pour l'irréversible : ce qu'un agent ne doit jamais faire n'existe pas dans son catalogue.
• Une liste blanche : les domaines Home Assistant autorisés sont nommés un par un. Un domaine qui apparaîtrait plus tard reste fermé tant qu'il n'est pas ajouté.
• Les secrets hors du dépôt : jetons et identifiants vivent dans deux emplacements ignorés par Git, et le Wi-Fi est lu sans ses clés.
• Un seul code pour deux usages : le serveur MCP et le tableau de bord partagent les clients d'API.
• Local d'abord : aucun port ouvert vers Internet, et un tableau de bord qui n'accepte que les requêtes de l'ordinateur.

Réseau maison est en service. Claude lit le réseau quand je le lui demande et n'agit qu'avec mon accord ; les réglages qui engagent la box se font toujours dans Freebox OS.