Automatizaciones MQTT con n8n: trigger, publicación y workflows

n8n se comunica con MQTT mediante dos nodos core: el MQTT Trigger, que se suscribe a topics y arranca un workflow por cada mensaje entrante, y el nodo MQTT, que publica mensajes desde cualquier paso de un workflow. Añade una credencial MQTT con el host, el puerto y el login de tu broker, coloca un trigger, activa el workflow y cada lectura de un sensor podrá llegar a Slack, al correo, a una base de datos, a una API HTTP o de vuelta a un dispositivo.

Este tutorial construye dos workflows reales —una alerta de temperatura y un comando de webhook a dispositivo— y muestra cómo probar cada paso con un segundo cliente MQTT.

Cómo encaja n8n en un sistema MQTT

n8n es una herramienta de automatización de workflows, no un broker. Se conecta a tu broker como un cliente MQTT normal:

Eso significa que todo lo que sabes sobre clientes MQTT aplica: cada trigger necesita un client ID único, la QoS se negocia por suscripción y las ACL del broker deciden qué puede leer y escribir n8n. Si ya usas Node-RED, el modelo es parecido; consulta Node-RED y MQTT como punto de comparación. La fortaleza de n8n es la larga lista de integraciones SaaS que tiene junto a los nodos MQTT.

Ejecuta n8n en local

La forma más rápida de experimentar es la imagen Docker oficial:

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

Abre http://localhost:5678, crea la cuenta de propietario y empieza un workflow nuevo. n8n Cloud funciona igual; la única diferencia es que el broker debe ser accesible desde internet, porque la conexión MQTT la abren los servidores de n8n, no tu portátil.

Crea la credencial MQTT

Añade cualquier nodo MQTT, abre Credential to connect with y elige Create new credential. La credencial MQTT tiene estos campos importantes:

Usa TLS (mqtts en 8883) para cualquier cosa que vaya más allá de una prueba rápida: la credencial se guarda una vez y la reutilizan todos los nodos, así que no hay motivo para enviar contraseñas en texto plano. n8n prueba la conexión al guardar; si falla, el texto del error suele ser el reason code del CONNACK del broker. Búscalo en la herramienta de reason codes MQTT.

Workflow 1: alerta de temperatura

El primer workflow escucha lecturas de sensores y envía un mensaje cuando un valor supera un umbral.

Paso 1 — MQTT Trigger. Pon en Topics testmqtt/n8n/+/temperature. El campo acepta una lista separada por comas y los comodines + y # funcionan como siempre (comprueba tus filtros con el topic matcher). En Options, activa JSON Parse Body para que el payload se convierta en un objeto, y activa Only Message si no necesitas el topic en pasos posteriores. Conserva el topic cuando un workflow gestiona muchos dispositivos.

Con ambas opciones como se indica, un mensaje llega como un item así:

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

Paso 2 — Nodo IF. Añade una condición: el número {{ $json.message.value }} es mayor que 30.

Paso 3 — Notificar. En la rama true añade un nodo de Slack, Telegram, Discord o Send Email. Un texto útil es:

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

El split('/')[2] extrae el ID del dispositivo del topic, y por eso compensa una estructura coherente; consulta buenas prácticas de diseño de topics.

Pruébalo antes de activarlo

Haz clic en Execute workflow (o Listen for test event en el trigger). El trigger espera ahora un mensaje. Publica una lectura desde una terminal o desde el cliente MQTT online:

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

El workflow se ejecuta una vez y puedes inspeccionar los datos en cada nodo. Publica un segundo mensaje con "value": 22 para confirmar que la rama false no hace nada.

Workflow 2: de webhook a comando de dispositivo

La dirección contraria es igual de habitual: algo fuera del mundo MQTT (un formulario, un calendario, un evento de CRM, otra API) debe encender un dispositivo.

1. Nodo Webhook, método POST, path lamp. Su URL de prueba se parece a http://localhost:5678/webhook-test/lamp.
2. Nodo IF que comprueba una cabecera con un secreto compartido, por ejemplo que {{ $json.headers['x-api-key'] }} sea igual a un valor guardado en n8n; no dejes que cualquiera en internet publique hacia tus dispositivos.
3. Nodo MQTT con Topic testmqtt/n8n/lamp-1/set. Desactiva Send Input Data y pon en Message {{ $json.body.state }}. En las opciones elige QoS 1 y deja Retain desactivado para comandos puntuales.

Con Send Input Data activado, n8n publica todo el item de entrada como JSON: práctico para reenviar, pero normalmente demasiado para un dispositivo que espera ON u OFF.

Observa el topic de comandos en una terminal y llama al webhook en otra:

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"}'

La terminal 1 debería mostrar testmqtt/n8n/lamp-1/set ON. Para el patrón inverso —mensajes MQTT que llaman a un endpoint HTTP— consulta MQTT a webhook.

Activa el workflow

Las ejecuciones de prueba solo funcionan mientras el editor escucha. Para procesar mensajes de forma permanente, guarda el workflow y actívalo (publícalo). A partir de ahí n8n mantiene la suscripción abierta en segundo plano y cada mensaje crea una ejecución que puedes revisar en la lista de ejecuciones.

Dos ajustes importan cuando el tráfico es real:

• Volumen de ejecuciones. Cada mensaje es una ejecución. Un sensor que publica una vez por segundo crea 86.400 ejecuciones al día, lo que llena el historial y consume CPU. Agrega en el edge, publica con menos frecuencia o suscríbete a un topic de "eventos" en lugar de telemetría cruda.
• Orden. El trigger procesa los mensajes en paralelo por defecto. Si el orden importa (cambios de estado del mismo dispositivo), desactiva el procesamiento paralelo en las opciones del trigger para que los mensajes se gestionen uno tras otro.

Garantías de entrega y reinicios

n8n es un cliente, así que sus garantías de entrega son las del broker para esa suscripción:

• Los mensajes QoS 0 publicados mientras n8n se reinicia se pierden.
• QoS 1 con una sesión persistente (Clean Session desactivado y un client ID fijo) permite que el broker encole mensajes mientras n8n está caído y los entregue al reconectar. Solo funciona en un broker que conserve sesiones: el endpoint de pruebas compartido broker.connectmq.com no almacena sesiones offline, así que pruébalo contra tu propia instancia privada de broker.
• Los mensajes retenidos se entregan en cuanto el trigger se suscribe, así que un workflow activado puede dispararse una vez por cada topic retenido que coincida. Suele ser lo deseado para topics de estado y una sorpresa para topics de alertas; consulta mensajes retenidos.

Si ejecutas n8n en queue mode con varios workers, los triggers siguen viviendo en la instancia principal. No arranques varias instancias principales con el mismo workflow MQTT activo, o cada mensaje se procesará varias veces.

Checklist de resolución de problemas

Observa tus topics de n8n en el navegador

n8n convierte mensajes MQTT en workflows sin escribir un servicio: un trigger, unos cuantos nodos y un publish MQTT cubren la mayoría de casos de alertas y comandos. Prueba cada workflow con un segundo cliente antes de activarlo, dale a n8n su propio usuario restringido en el broker y deja la telemetría de alta frecuencia fuera de los workflows para que el número de ejecuciones siga siendo razonable.

Preguntas frecuentes