Automações MQTT com n8n: trigger, publicação e workflows

O n8n conversa com MQTT por meio de dois nós core: o MQTT Trigger, que assina topics e inicia um workflow para cada mensagem recebida, e o nó MQTT, que publica mensagens a partir de qualquer etapa de um workflow. Adicione uma credencial MQTT com host, porta e login do seu broker, coloque um trigger, ative o workflow e cada leitura de sensor pode seguir para Slack, e-mail, um banco de dados, uma API HTTP ou de volta para um dispositivo.

Este tutorial monta dois workflows reais — um alerta de temperatura e um comando de webhook para dispositivo — e mostra como testar cada etapa com um segundo cliente MQTT.

Como o n8n se encaixa em um sistema MQTT

O n8n é uma ferramenta de automação de workflows, não um broker. Ele se conecta ao seu broker como um cliente MQTT comum:

Ou seja, tudo o que você sabe sobre clientes MQTT vale aqui: cada trigger precisa de um client ID único, a QoS é negociada por assinatura e as ACLs do broker decidem o que o n8n pode ler e escrever. Se você já usa Node-RED, o modelo é parecido; veja Node-RED e MQTT como ponto de comparação. A força do n8n é a longa lista de integrações SaaS ao lado dos nós MQTT.

Rode o n8n localmente

O jeito mais rápido de experimentar é a imagem 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

Abra http://localhost:5678, crie a conta de owner e comece um workflow novo. O n8n Cloud funciona do mesmo jeito; a única diferença é que o broker precisa estar acessível pela internet, porque a conexão MQTT é aberta pelos servidores do n8n, não pelo seu notebook.

Crie a credencial MQTT

Adicione qualquer nó MQTT, abra Credential to connect with e escolha Create new credential. A credencial MQTT tem estes campos importantes:

Use TLS (mqtts na 8883) para qualquer coisa além de um teste rápido: a credencial é salva uma vez e reutilizada por todos os nós, então não há motivo para mandar senhas em texto puro. O n8n testa a conexão ao salvar; se falhar, o texto do erro geralmente é o reason code do CONNACK do broker. Consulte-o na ferramenta de reason codes MQTT.

Workflow 1: alerta de temperatura

O primeiro workflow escuta leituras de sensores e envia uma mensagem quando um valor passa de um limite.

Etapa 1 — MQTT Trigger. Defina Topics como testmqtt/n8n/+/temperature. O campo aceita uma lista separada por vírgulas, e os curingas + e # funcionam normalmente (confira seus filtros com o topic matcher). Em Options, ative JSON Parse Body para o payload virar um objeto, e ative Only Message se você não precisar do topic nas etapas seguintes. Mantenha o topic quando um workflow atende muitos dispositivos.

Com as duas opções como mostrado, uma mensagem chega como um item assim:

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

Etapa 2 — Nó IF. Adicione uma condição: o número {{ $json.message.value }} é maior que 30.

Etapa 3 — Notificar. No ramo true, adicione um nó de Slack, Telegram, Discord ou Send Email. Um texto útil é:

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

O split('/')[2] tira o ID do dispositivo do topic, e é por isso que uma estrutura consistente compensa; veja boas práticas de design de topics.

Teste antes de ativar

Clique em Execute workflow (ou Listen for test event no trigger). Agora o trigger espera uma mensagem. Publique uma leitura pelo terminal ou pelo 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}'

O workflow executa uma vez e você pode inspecionar os dados em cada nó. Publique uma segunda mensagem com "value": 22 para confirmar que o ramo false fica quieto.

Workflow 2: de webhook para comando no dispositivo

A direção oposta é tão comum quanto: algo fora do mundo MQTT (um formulário, uma agenda, um evento de CRM, outra API) precisa ligar um dispositivo.

1. Nó Webhook, método POST, path lamp. A URL de teste fica parecida com http://localhost:5678/webhook-test/lamp.
2. Nó IF que verifica um header com segredo compartilhado, por exemplo se {{ $json.headers['x-api-key'] }} é igual a um valor guardado no n8n — não deixe qualquer pessoa na internet publicar para os seus dispositivos.
3. Nó MQTT com Topic testmqtt/n8n/lamp-1/set. Desligue Send Input Data e defina Message como {{ $json.body.state }}. Nas opções, escolha QoS 1 e deixe Retain desligado para comandos momentâneos.

Com Send Input Data ligado, o n8n publica o item de entrada inteiro como JSON — útil para repassar dados, mas normalmente demais para um dispositivo que espera ON ou OFF.

Observe o topic de comandos em um terminal e chame o webhook em outro:

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

O terminal 1 deve mostrar testmqtt/n8n/lamp-1/set ON. Para o padrão inverso — mensagens MQTT chamando um endpoint HTTP — veja MQTT para webhook.

Ative o workflow

Execuções de teste só rodam enquanto o editor está escutando. Para processar mensagens de forma permanente, salve o workflow e ative-o (publique-o). A partir daí, o n8n mantém a assinatura aberta em segundo plano e cada mensagem cria uma execução que você pode revisar na lista de execuções.

Duas configurações importam quando o tráfego é real:

• Volume de execuções. Cada mensagem é uma execução. Um sensor publicando uma vez por segundo gera 86.400 execuções por dia, o que enche o histórico e consome CPU. Agregue no edge, publique com menos frequência ou assine um topic de "eventos" em vez de telemetria bruta.
• Ordem. Por padrão, o trigger processa mensagens em paralelo. Se a ordem importa (mudanças de estado do mesmo dispositivo), desligue o processamento paralelo nas opções do trigger para que as mensagens sejam tratadas uma após a outra.

Garantias de entrega e reinícios

O n8n é um cliente, então as garantias de entrega dele são as do broker para aquela assinatura:

• Mensagens QoS 0 publicadas enquanto o n8n reinicia se perdem.
• QoS 1 com sessão persistente (Clean Session desligado e client ID fixo) permite que o broker enfileire mensagens enquanto o n8n está fora e as entregue na reconexão. Isso só funciona em um broker que guarda sessões — o endpoint de testes compartilhado broker.connectmq.com não armazena sessões offline, então teste isso na sua própria instância privada de broker.
• Mensagens retidas são entregues assim que o trigger assina, então um workflow ativado pode disparar uma vez para cada topic retido que combinar. Geralmente é o que você quer em topics de estado e uma surpresa em topics de alerta; veja mensagens retidas.

Se você roda o n8n em queue mode com vários workers, os triggers continuam na instância principal. Não suba várias instâncias principais com o mesmo workflow MQTT ativo, senão cada mensagem será processada várias vezes.

Checklist de troubleshooting

Acompanhe seus topics do n8n no navegador

O n8n transforma mensagens MQTT em workflows sem você escrever um serviço: um trigger, alguns nós e um publish MQTT cobrem a maioria dos casos de alerta e comando. Teste cada workflow com um segundo cliente antes de ativá-lo, dê ao n8n um usuário restrito no broker e mantenha a telemetria de alta frequência fora dos workflows para que o número de execuções continue razoável.

Perguntas frequentes