Connecter MQTT à n8n : piloter capteurs et domotique depuis vos workflows

Un capteur à quinze euros publie une mesure toutes les trente secondes sur un broker Mosquitto. Home Assistant l'affiche, Zigbee2MQTT le relaie, Tasmota et ESPHome parlent le même langage. Mais dès qu'il faut croiser cette mesure avec la météo du lendemain, réveiller une astreinte ou faire analyser une dérive par un LLM, la domotique montre ses limites : elle sait afficher et déclencher, pas raisonner. n8n comble ce trou avec deux nodes et une credential. Ce guide détaille leurs paramètres réels, les mécanismes du protocole qui surprennent au début — QoS, retain, Last Will — et le point qu'on découvre trop tard : la connexion persistante d'un trigger.

MQTT en trois minutes

Un broker central — Mosquitto, EMQX, HiveMQ, ou celui intégré à Home Assistant — reçoit tous les messages. Les producteurs publient sur un topic, chaîne hiérarchique séparée par des slashes (maison/salon/temperature, usine/ligne2/moteur/vibration), les consommateurs s'abonnent et reçoivent ce qui y transite, sans jamais connaître les producteurs. Deux jokers assouplissent l'abonnement : + remplace un seul niveau (maison/+/temperature capte le salon et la cuisine, pas maison/salon/capteur1/temperature), # remplace tous les niveaux suivants et ne s'écrit qu'en fin de motif.

La différence de fond avec un webhook HTTP tient à la direction de la connexion : c'est le client qui l'ouvre vers le broker et la garde ouverte. Aucune redirection de port, aucune IP publique côté capteur — d'où l'intérêt pour une instance n8n auto-hébergée sur un Raspberry Pi. Ce choix a un coût mesurable : Víctor Seoane, Carlos Garcia-Rubio, Florina Almenares et Celeste Campo comparent MQTT et CoAP sur équipements contraints dans « Performance evaluation of CoAP and MQTT with security support for IoT environments », publié en 2021 dans Computer Networks (vol. 197, art. 108338 — voir sur Google Scholar). Ils mesurent bande passante et charge CPU — qui se traduisent en consommation électrique — et montrent que sécuriser le transport comme relever le niveau de fiabilité pèse sur le budget énergétique d'un capteur sur batterie.

QoS, retain et Last Will

QoS 0 (au plus une fois) : le message part, personne ne confirme. Coût minimal, parfait pour une mesure que la suivante rattrape. QoS 1 (au moins une fois) : le récepteur accuse réception, et sans accusé l'émetteur renvoie — donc le même message peut arriver deux fois et déclencher deux exécutions n8n. La discipline est celle du webhook rejoué : un identifiant d'événement stocké, et on ignore ce qui a déjà été traité. QoS 2 (exactement une fois) : quatre allers-retours réseau, pour les ordres qu'on ne peut ni perdre ni dupliquer.

Le flag retain demande au broker de conserver le dernier message d'un topic et de le redélivrer à tout nouvel abonné : n8n connaît la dernière température dès qu'il s'abonne. Le revers surprend — à chaque activation ou redémarrage, le Trigger recevra ce message conservé et déclenchera une exécution, même si le capteur n'a rien publié depuis trois jours. Le Last Will and Testament, lui, est déclaré par le client à la connexion et publié par le broker à sa place s'il disparaît brutalement : c'est ainsi que Zigbee2MQTT signale offline. La credential n8n n'expose pas de champ de testament, mais un Trigger abonné à maison/+/status transforme la disparition d'un capteur en alerte.

La credential MQTT

• Protocol : trois valeurs seulement, Mqtt, Mqtts et Ws. Pas d'entrée wss dédiée ;
• Host et Port (1883 par défaut, 8883 en TLS par convention) ;
• Username et Password : n8n ne transmet les identifiants que si les deux champs sont renseignés. Un broker en username seul verra n8n se présenter en anonyme ;
• Clean Session, activé par défaut ; le désactiver permet de recevoir les messages QoS 1 et 2 arrivés pendant que le client était hors ligne ;
• Client ID : laissé vide, n8n en génère un aléatoire de la forme mqttjs_xxxxxxxx ;
• SSL, qui fait apparaître CA Certificates et Passwordless (authentification par certificat), cette dernière déverrouillant Client Certificate, Client Key et Reject Unauthorized Certificate — à false par défaut, donc le certificat du broker n'est pas validé tant que vous ne l'activez pas.

Ces valeurs sont chiffrées en base comme tous vos identifiants API. Et si n8n tourne en Docker avec le broker sur l'hôte, localhost dans Host échoue en ECONNREFUSED, comme pour n'importe quel service local.

Le node MQTT : publier

Topic (obligatoire) ; Send Input Data, activé par défaut, qui publie le JSON de l'item d'entrée sérialisé tel quel ; Message, visible uniquement si Send Input Data est désactivé, pour une charge utile littérale comme ON ou 21.5 ; et les options QoS (Received at Most Once, Received at Least Once, Exactly Once, 0 par défaut) et Retain (désactivé par défaut). Le node publie un message par item d'entrée, ouvre sa connexion au début de l'exécution et la ferme à la fin, ce qui garantit la réception des accusés QoS 1 et 2. Il ressort ses items inchangés, et sert aussi d'outil à un AI Agent.

Le MQTT Trigger : s'abonner

Un seul champ obligatoire, Topics, qui accepte plusieurs valeurs séparées par des virgules, les jokers + et #, et un QoS par topic écrit après un deux-points :

maison/salon/temperature:1,maison/+/mouvement,usine/ligne2/#:2

Sans deux-points, le QoS vaut 0. Attention, cette syntaxe s'écrit bien dans Topics : ce n'est pas une option de la collection Options, qui en compte trois. JSON Parse Body (désactivé par défaut) tente de parser la charge utile en objet et — comportement important — conserve silencieusement la chaîne brute si le parsing échoue ; Only Message ne renvoie que le contenu, sans la propriété topic ; Parallel Processing, activé par défaut, traite les messages en parallèle, le désactiver préservant l'ordre au prix d'un goulot d'étranglement. L'item par défaut :

{
  "topic": "maison/salon/temperature",
  "message": { "temperature": 21.4, "humidite": 48 }
}

Garder topic est le bon réflexe avec un joker : c'est la seule information qui dit d'où vient la mesure, et sur laquelle un node IF ou Switch routera.

Le point critique : la connexion persistante

Un webhook attend qu'on frappe à la porte. Un MQTT Trigger, non : à l'activation du workflow, il ouvre une connexion TCP vers le broker, souscrit, et la maintient ouverte. Trois conséquences.

1. Workflow désactivé = aucun abonnement. Rien n'est mis en attente pour vous, contrairement à une queue RabbitMQ qui accumule ses messages.
2. Redémarrage de n8n = coupure. Les messages publiés entre l'arrêt et la reconnexion sont perdus, sauf si Clean Session est désactivé, le Client ID fixe et la souscription en QoS 1 ou 2 : les trois conditions vont ensemble.
3. Client ID dupliqué = guerre de reconnexion. Le protocole impose l'unicité du Client ID : un client qui se connecte avec un identifiant déjà utilisé fait déconnecter l'autre. Deux instances devant le même broker — préproduction et production, bascule bleu-vert — avec la même credential et un Client ID figé, et les deux se battent en boucle. Le mode queue avec Redis ne réplique pas la souscription sur chaque worker, mais la règle tient : un Client ID distinct par instance.

Le symptôme est le même dans les trois cas : rien ne se passe. Aucune exécution en erreur, juste un workflow muet. La supervision de l'instance doublée d'un capteur de battement — un équipement qui publie chaque minute, un workflow qui s'alarme de son silence — reste la seule détection fiable.

Le débit : un message, une exécution

Un capteur qui publie chaque seconde, c'est 86 400 exécutions par jour et par topic, donc autant de lignes en base. Le sujet rejoint le nettoyage des exécutions n8n, sauf qu'ici on agit à la source : séparer les topics « mesures » et « événements » et ne s'abonner qu'aux seconds, filtrer côté broker en souscrivant à local/serveur/alerte plutôt qu'à maison/#, agréger en amont (une moyenne sur cinq minutes divise le volume par trois cents), désactiver la sauvegarde des exécutions de production réussies dans les réglages du workflow.

Cas d'usage

Le premier réflexe, c'est l'alerte d'un local technique : abonnement à local/serveur/+, comparaison à des seuils, notification de l'astreinte. Vient le bouton physique, un bouton Zigbee qui publie sur maison/bureau/bouton : le webhook le moins cher du monde. Une passerelle Home Assistant met en forme les événements dans un bot Telegram piloté par IA. L'historisation insère chaque message via le node Postgres ou dans une Data Table n8n, historique qu'un LLM relira pour diagnostiquer une série anormale. Et l'inverse fonctionne : publier une consigne sur maison/salon/consigne d'après la météo du matin.

Les pièges classiques

• Clean Session laissé activé sur un flux critique : toute coupure de n8n crée un trou dans les données, sans message d'erreur ;
• La boucle infinie : un workflow déclenché par maison/# qui republie son résultat sur maison/salon/log se redéclenche lui-même, à vitesse machine. Publiez toujours sur une branche à laquelle vous n'êtes pas abonné — et méfiez-vous du joker #, qui sur un broker partagé avec Home Assistant capte aussi les topics de découverte et de service ;
• Un broker sans TLS ni authentification exposé sur Internet : Seyed Ali Ghazi Asgar et Narasimha Reddy, dans « Analysis of Misconfigured IoT MQTT Deployments and a Lightweight Exposure Detection System » présenté à l'atelier SDIoTSec du NDSS 2025 (voir sur Google Scholar), analysent les déploiements MQTT mal configurés et les scénarios d'attaque qu'ils rendent possibles. Un broker ouvert, c'est un attaquant qui lit vos capteurs et publie sur vos topics de commande ;
• Les charges utiles non-JSON : Tasmota publie parfois ON en texte brut, d'autres équipements du binaire. Le parsing échoue en silence, testez donc le type avant un $json.message.temperature qui renverrait undefined ;
• Le message retain rejoué à chaque activation : prévoyez un garde-fou sur l'horodatage avant d'envoyer une alerte périmée ;
• Aucune erreur visible quand la connexion tombe : un Error Workflow ne se déclenchera pas, puisqu'il n'y a plus d'exécution du tout.

En résumé

Brancher MQTT sur n8n prend cinq minutes : une credential (Protocol, Host, Port 1883, Client ID), un MQTT Trigger dont le champ Topics accepte virgules, jokers et QoS en suffixe :1, et un node MQTT avec ses options QoS et Retain. Le reste tient en trois réflexes : traiter le QoS 1 comme une source de doublons, retenir que la souscription est une connexion vivante qui meurt en silence, et arbitrer dès le départ entre « je m'abonne à tout » et un budget d'exécutions tenable.

Pour aller plus loin

Une alerte de capteur suit le même chemin qu'une alerte d'email : dédoublonner, prioriser, enrichir, router vers la bonne personne. Le Pack Inbox IA (79 €) applique cette logique de tri au flux entrant, et elle se transpose telle quelle à un flux MQTT bruyant. Pour garder une trace horodatée des mesures d'un local technique ou d'une chaîne du froid, le Pack Conformité & Audit (149 €) montre comment construire une piste d'audit qui tient l'inspection.