Automatisations MQTT avec n8n : trigger, publication et workflows

n8n dialogue avec MQTT grâce à deux nœuds core : le MQTT Trigger, qui s'abonne à des topics et lance un workflow pour chaque message reçu, et le nœud MQTT, qui publie des messages depuis n'importe quelle étape d'un workflow. Ajoutez un credential MQTT avec l'hôte, le port et les identifiants de votre broker, posez un trigger, activez le workflow, et chaque mesure de capteur peut partir vers Slack, un e-mail, une base de données, une API HTTP ou revenir vers un appareil.

Ce tutoriel construit deux workflows concrets — une alerte de température et une commande webhook vers appareil — et montre comment tester chaque étape avec un second client MQTT.

La place de n8n dans un système MQTT

n8n est un outil d'automatisation de workflows, pas un broker. Il se connecte à votre broker comme un client MQTT ordinaire :

Tout ce que vous savez sur les clients MQTT s'applique donc : chaque trigger a besoin d'un client ID unique, la QoS se négocie par abonnement et les ACL du broker décident de ce que n8n peut lire et écrire. Si vous utilisez déjà Node-RED, le modèle est proche ; voyez Node-RED et MQTT pour comparer. La force de n8n, c'est la longue liste d'intégrations SaaS disponibles à côté des nœuds MQTT.

Lancer n8n en local

Le plus rapide pour expérimenter est l'image Docker officielle :

docker volume create n8n_data
docker run -it --rm --name n8n \
  -p 5678:5678 \
  -v n8n_data:/home/node/.n8n \
  docker.n8n.io/n8nio/n8n

Ouvrez http://localhost:5678, créez le compte propriétaire et démarrez un nouveau workflow. n8n Cloud fonctionne de la même façon ; seule différence, le broker doit être joignable depuis Internet, car la connexion MQTT est ouverte par les serveurs de n8n, pas par votre portable.

Créer le credential MQTT

Ajoutez un nœud MQTT, ouvrez Credential to connect with et choisissez Create new credential. Le credential MQTT comporte ces champs importants :

Utilisez TLS (mqtts sur 8883) dès que vous dépassez le simple test : le credential est enregistré une fois et réutilisé par tous les nœuds, rien ne justifie d'envoyer des mots de passe en clair. n8n teste la connexion à l'enregistrement ; en cas d'échec, le texte d'erreur correspond généralement au reason code du CONNACK du broker. Consultez-le dans l'outil des reason codes MQTT.

Workflow 1 : alerte de température

Le premier workflow écoute les mesures des capteurs et envoie un message quand une valeur dépasse un seuil.

Étape 1 — MQTT Trigger. Renseignez Topics avec testmqtt/n8n/+/temperature. Le champ accepte une liste séparée par des virgules, et les wildcards + et # fonctionnent comme d'habitude (vérifiez vos filtres avec le topic matcher). Dans Options, activez JSON Parse Body pour transformer le payload en objet, et Only Message si vous n'avez pas besoin du topic par la suite. Gardez le topic lorsqu'un workflow gère de nombreux appareils.

Avec les options indiquées, un message arrive sous la forme d'un item comme celui-ci :

{
  "topic": "testmqtt/n8n/greenhouse-1/temperature",
  "message": { "value": 31.4, "unit": "C", "ts": 1760700000 }
}

Étape 2 — Nœud IF. Ajoutez une condition : le nombre {{ $json.message.value }} est supérieur à 30.

Étape 3 — Notifier. Sur la branche true, ajoutez un nœud Slack, Telegram, Discord ou Send Email. Un texte utile :

🌡 {{ $json.topic.split('/')[2] }} est à {{ $json.message.value }} °{{ $json.message.unit }}

Le split('/')[2] extrait l'ID de l'appareil du topic — c'est pourquoi une arborescence cohérente est payante ; voir les bonnes pratiques de conception des topics.

Tester avant d'activer

Cliquez sur Execute workflow (ou Listen for test event sur le trigger). Le trigger attend maintenant un message. Publiez une mesure depuis un terminal ou depuis le client MQTT en ligne :

mosquitto_pub -h broker.connectmq.com -p 1883 \
  -t testmqtt/n8n/greenhouse-1/temperature \
  -m '{"value": 31.4, "unit": "C", "ts": 1760700000}'

Le workflow s'exécute une fois et vous pouvez inspecter les données de chaque nœud. Publiez un second message avec "value": 22 pour vérifier que la branche false reste muette.

Workflow 2 : du webhook à la commande d'appareil

Le sens inverse est tout aussi courant : quelque chose hors du monde MQTT (un formulaire, un agenda, un événement CRM, une autre API) doit piloter un appareil.

1. Nœud Webhook, méthode POST, path lamp. Son URL de test ressemble à http://localhost:5678/webhook-test/lamp.
2. Nœud IF qui vérifie un en-tête contenant un secret partagé, par exemple que {{ $json.headers['x-api-key'] }} soit égal à une valeur stockée dans n8n — ne laissez pas n'importe qui sur Internet publier vers vos appareils.
3. Nœud MQTT avec Topic testmqtt/n8n/lamp-1/set. Désactivez Send Input Data et mettez Message à {{ $json.body.state }}. Dans les options, choisissez QoS 1 et laissez Retain désactivé pour les commandes ponctuelles.

Avec Send Input Data activé, n8n publie l'item d'entrée complet en JSON — pratique pour relayer, mais souvent trop pour un appareil qui attend ON ou OFF.

Surveillez le topic de commande dans un terminal et appelez le webhook dans un autre :

mosquitto_sub -h broker.connectmq.com -p 1883 -t 'testmqtt/n8n/+/set' -v

curl -X POST http://localhost:5678/webhook-test/lamp \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: change-me' \
  -d '{"state": "ON"}'

Le terminal 1 doit afficher testmqtt/n8n/lamp-1/set ON. Pour le schéma inverse — des messages MQTT qui appellent un endpoint HTTP — voir MQTT vers webhook.

Activer le workflow

Les exécutions de test ne tournent que tant que l'éditeur écoute. Pour traiter les messages en permanence, enregistrez le workflow et activez-le (publiez-le). Dès lors, n8n garde l'abonnement ouvert en arrière-plan et chaque message crée une exécution consultable dans la liste des exécutions.

Deux réglages comptent dès que le trafic est réel :

• Volume d'exécutions. Chaque message est une exécution. Un capteur qui publie une fois par seconde génère 86 400 exécutions par jour, ce qui remplit l'historique et consomme du CPU. Agrégez en edge, publiez moins souvent ou abonnez-vous à un topic « événements » plutôt qu'à la télémétrie brute.
• Ordre. Par défaut, le trigger traite les messages en parallèle. Si l'ordre compte (changements d'état d'un même appareil), désactivez le traitement parallèle dans les options du trigger pour traiter les messages l'un après l'autre.

Garanties de livraison et redémarrages

n8n est un client : ses garanties de livraison sont celles du broker pour cet abonnement.

• Les messages QoS 0 publiés pendant un redémarrage de n8n sont perdus.
• QoS 1 avec une session persistante (Clean Session désactivé et client ID fixe) permet au broker de mettre les messages en file pendant l'arrêt de n8n et de les livrer à la reconnexion. Cela ne fonctionne qu'avec un broker qui conserve les sessions — l'endpoint de test partagé broker.connectmq.com ne stocke pas de sessions hors ligne, testez donc ce point sur votre propre instance privée de broker.
• Les messages retenus sont livrés dès que le trigger s'abonne : un workflow activé peut donc se déclencher une fois par topic retenu correspondant. C'est souvent voulu pour les topics d'état et surprenant pour les topics d'alerte ; voir messages retenus.

Si vous faites tourner n8n en queue mode avec plusieurs workers, les triggers restent sur l'instance principale. Ne lancez pas plusieurs instances principales avec le même workflow MQTT actif, sinon chaque message sera traité plusieurs fois.

Check-list de dépannage

Observer vos topics n8n dans le navigateur

n8n transforme des messages MQTT en workflows sans écrire de service : un trigger, quelques nœuds et une publication MQTT couvrent la plupart des cas d'alerte et de commande. Testez chaque workflow avec un second client avant de l'activer, donnez à n8n son propre utilisateur restreint sur le broker et gardez la télémétrie à haute fréquence hors des workflows pour que le nombre d'exécutions reste raisonnable.

Questions fréquentes