MQTT and Home Assistant: The Complete Beginner's Guide (2026)

Most Home Assistant integrations talk to devices through their own protocols — Zigbee, Z-Wave, ESPHome's native API. That works until you hit a device that speaks none of them. An ESP board running Tasmota. A commercial sensor that only outputs MQTT. A custom microcontroller project. An external system that needs to push data into HA without a dedicated integration.

MQTT is the glue layer. It is a lightweight publish/subscribe messaging protocol that almost everything in the IoT world can speak. If you run Home Assistant with any seriousness, you will eventually need it.

I use MQTT across my 700+ entity system for devices and patterns that do not fit neatly into any other integration. This guide covers everything: what MQTT is, how to install and configure it, manual YAML configs, auto-discovery, ESP device integration, and debugging.

What MQTT Actually Is

MQTT (Message Queuing Telemetry Transport) is a messaging protocol built for constrained devices and unreliable networks. Three concepts:

**Broker** — A server that receives all messages and routes them to subscribers. Think of it as a post office. In Home Assistant, the broker is almost always the Mosquitto add-on.

**Topics** — Hierarchical strings that organize messages. Like file paths: `home/living_room/temperature`, `home/garage/door/state`. Publishers send messages to a topic. Subscribers listen on a topic.

**Publish/Subscribe (Pub/Sub)** — Devices do not talk to each other directly. A temperature sensor *publishes* its reading to `home/office/temperature`. Home Assistant *subscribes* to that topic and gets every message. The sensor does not know or care who is listening. HA does not need to know the sensor's IP address.

This decoupling is the entire point. Any device can publish to any topic, and any number of subscribers can listen. Add a new sensor, point it at the broker, and every subscriber gets the data automatically.

MQTT vs. HTTP vs. WebSocket

**HTTP** is request/response — HA has to poll the device, or the device has to call an HA endpoint. Fine for occasional updates, wasteful for real-time data, and the device needs to know HA's address.

**WebSocket** is persistent and bidirectional, but heavyweight for a $3 microcontroller running on a coin cell.

**MQTT** is persistent, lightweight (2-byte minimum header), and the device only needs to know the broker address. A microcontroller with 32KB of RAM can run an MQTT client. That is why it became the IoT standard.

Why Home Assistant Users Need MQTT

You need MQTT if any of these apply:

Even if you primarily use ESPHome (which uses its own native API), having a broker running opens up patterns that no other integration handles cleanly.

Install Mosquitto Broker

If you are on Home Assistant OS or Supervised, Mosquitto is a one-click add-on.

1. Go to **Settings > Add-ons > Add-on Store**

2. Search for **Mosquitto broker**

3. Click **Install**, then **Start**

4. Enable **Start on boot** and **Watchdog**

Before starting Mosquitto, create a dedicated MQTT user. Go to **Settings > People > Users**, click **Add User**, and create a user (for example, `mqtt_user` with a strong password). This is the account that devices will authenticate with. Do not use your admin account.

The add-on auto-configures to listen on port 1883 (unencrypted) and 1884 (WebSocket). For a local network behind a firewall, this is fine. For anything exposed to the internet, set up TLS — but that is a separate topic.

Configure the MQTT Integration

After Mosquitto is running, HA usually auto-discovers it. If not:

1. Go to **Settings > Devices & Services > Add Integration**

2. Search for **MQTT**

3. It will detect the Mosquitto add-on automatically and pre-fill the broker address

4. Enter the MQTT user credentials you created

5. Click **Submit**

That is it. HA is now connected to the broker and ready to subscribe to topics.

Verify the Connection

Go to **Developer Tools > MQTT** (available once the integration is active). You will see two boxes: one for subscribing and one for publishing.

Subscribe to `#` (the wildcard that matches all topics). Then publish a test message:

You should see your message appear in the subscription log immediately. If it does, the broker and integration are working.

Manual MQTT Sensors in YAML

Auto-discovery (covered below) handles most devices. But sometimes you need to define an entity manually — a custom device publishing to a non-standard topic, or a sensor you want to shape specifically.

Temperature Sensor

mqtt:

sensor:

state_topic: "workshop/sensor/temperature"

unit_of_measurement: "°F"

device_class: temperature

state_class: measurement

value_template: "{{ value_json.temperature }}"

This subscribes to `workshop/sensor/temperature` and expects a JSON payload like `{"temperature": 72.5}`. The `value_template` extracts the value. `device_class` and `state_class` tell HA how to display it and whether to track long-term statistics.

Binary Sensor (Door/Window)

mqtt:

binary_sensor:

state_topic: "shed/door/state"

payload_on: "OPEN"

payload_off: "CLOSED"

device_class: door

The device publishes `OPEN` or `CLOSED` as a plain string. No JSON parsing needed. HA maps them to on/off states.

Switch (Controllable Device)

Switches are bidirectional — HA reads the state *and* sends commands.

mqtt:

switch:

state_topic: "workshop/heater/state"

command_topic: "workshop/heater/set"

payload_on: "ON"

payload_off: "OFF"

state_on: "ON"

state_off: "OFF"

retain: true

When you toggle this switch in HA, it publishes `ON` or `OFF` to `workshop/heater/set`. The device listens on that topic, acts on the command, and publishes its actual state back to `workshop/heater/state`. The `retain: true` flag tells the broker to store the last command so devices that reconnect after a power cycle get the current desired state immediately.

JSON Payload with Multiple Values

A single MQTT topic can carry multiple sensor readings. One ESP board publishing `{"temp": 71.2, "humidity": 45, "pressure": 1013.2}` to `workshop/sensor/data` gives you three sensors:

mqtt:

sensor:

state_topic: "workshop/sensor/data"

unit_of_measurement: "°F"

device_class: temperature

value_template: "{{ value_json.temp }}"

state_topic: "workshop/sensor/data"

unit_of_measurement: "%"

device_class: humidity

value_template: "{{ value_json.humidity }}"

state_topic: "workshop/sensor/data"

unit_of_measurement: "hPa"

device_class: atmospheric_pressure

value_template: "{{ value_json.pressure }}"

All three sensors subscribe to the same topic. Each one extracts a different field from the JSON.

MQTT Discovery vs. Manual Config

Most modern MQTT devices support **Home Assistant MQTT Discovery**. The device publishes a configuration message to a special topic (`homeassistant/sensor/workshop_temp/config`), and HA automatically creates the entity with the correct name, type, units, and topic mappings.

**Zigbee2MQTT** uses discovery by default — every paired Zigbee device appears in HA without any YAML. **Tasmota** supports it too (enable `SetOption19 0` and configure the discovery prefix).

When to use discovery:

When to use manual YAML:

Both approaches can coexist. I use discovery for Zigbee2MQTT devices and manual YAML for custom ESP boards and webhook bridges.

ESP Devices Over MQTT

ESPHome uses its native API by default, but you can configure any ESP device to use MQTT instead. This is useful when you are running Arduino firmware, MicroPython, or Tasmota rather than ESPHome.

Here is a minimal Arduino sketch (ESP32) that publishes temperature to MQTT:

#include <WiFi.h>

#include <PubSubClient.h>

#include <DHT.h>

#define DHTPIN 4

#define DHTTYPE DHT22

WiFiClient espClient;

PubSubClient client(espClient);

DHT dht(DHTPIN, DHTTYPE);

void setup() {

WiFi.begin("your_ssid", "your_password");

while (WiFi.status() != WL_CONNECTED) delay(500);

client.setServer("192.168.1.x", 1883); // your broker IP

dht.begin();

}

void reconnect() {

while (!client.connected()) {

client.connect("workshop-sensor", "mqtt_user", "mqtt_pass");

delay(1000);

}

}

void loop() {

if (!client.connected()) reconnect();

client.loop();

float temp = dht.readTemperature(true); // Fahrenheit

if (!isnan(temp)) {

char payload[50];

snprintf(payload, 50, "{\"temperature\": %.1f}", temp);

client.publish("workshop/sensor/temperature", payload);

}

delay(30000); // publish every 30 seconds

}

Point the MQTT sensor YAML from the earlier example at `workshop/sensor/temperature`, and the readings show up in HA. No integration to install, no discovery needed. The device just publishes and HA just listens.

For Tasmota devices, MQTT is the default transport. Flash Tasmota, configure the broker address and credentials in the Tasmota web UI under **Configuration > Configure MQTT**, and enable discovery. The device appears in HA within seconds.

Webhook-to-MQTT Bridge Pattern

Some devices — IP cameras, NVRs, alarm panels — cannot publish to MQTT directly but can fire HTTP webhooks. You can bridge them into MQTT using a Home Assistant automation:

automation:

alias: "Camera Webhook to MQTT Bridge"

trigger:

webhook_id: camera_front_motion

allowed_methods:

action:

data:

topic: "cameras/front/motion"

payload: "detected"

retain: false

Now any automation, sensor, or external system that subscribes to `cameras/front/motion` gets the event. You have turned a one-shot HTTP callback into a pub/sub message that any number of consumers can use.

I use this pattern for my Vivotek cameras. The NVR fires a webhook on motion detection, HA catches it and publishes to MQTT, and multiple automations react — one sends a notification, another flags a boolean, a third logs the event. The camera does not need to know about any of them.

Automations That Trigger on MQTT

You can trigger automations directly from MQTT messages without defining a sensor entity at all:

automation:

alias: "Doorbell via MQTT"

trigger:

topic: "home/doorbell/pressed"

payload: "true"

action:

target:

entity_id: tts.piper

data:

media_player_entity_id: media_player.living_room

message: "Someone is at the front door."

data:

title: "Doorbell"

message: "Someone is at the front door"

This fires when any device publishes `true` to `home/doorbell/pressed`. No sensor entity needed. Useful for event-driven patterns where you do not need to track state — just react to a message.

You can also omit the `payload` filter to trigger on any message to that topic, then use the payload in templates:

automation:

alias: "MQTT Alert Handler"

trigger:

topic: "home/alerts/+"

action:

data:

title: "Alert"

message: "{{ trigger.topic.split('/')[-1] }}: {{ trigger.payload }}"

The `+` wildcard matches any single topic level. A message to `home/alerts/flood` with payload `basement sensor triggered` sends a notification reading "flood: basement sensor triggered". One automation handles every alert type.

Debugging with MQTT Explorer

When something is not working, you need to see what is actually on the broker. [MQTT Explorer](https://mqtt-explorer.com/) is a free desktop app that connects to your broker and shows every topic, payload, and retained message in a tree view.

Install it, connect to your Mosquitto broker (IP of your HA instance, port 1883, MQTT user credentials), and you get a live view of all MQTT traffic.

Common debugging scenarios:

MQTT Explorer is the single most useful debugging tool for any MQTT-based setup. Install it before you need it.

Quick Reference: MQTT Configuration Cheat Sheet

| Entity Type | Required Topics | Payload Format |

|---|---|---|

| `sensor` | `state_topic` | String or JSON |

| `binary_sensor` | `state_topic` | `payload_on` / `payload_off` |

| `switch` | `state_topic` + `command_topic` | ON/OFF strings |

| `light` | `state_topic` + `command_topic` | JSON with brightness, color, etc. |

| `cover` | `state_topic` + `command_topic` | OPEN/CLOSE/STOP |

| `climate` | Multiple topics | JSON with temp, mode, fan |

For any entity type, check the [MQTT integration docs](https://www.home-assistant.io/integrations/mqtt/) for the full list of supported options. The manual config is verbose but gives you complete control.

What to Build Next

Once your broker is running and you are comfortable with the basics:

MQTT is infrastructure. Once it is in place, it quietly handles every integration edge case that comes up.

---

If you want production-tested automations that work with MQTT sensors, webhooks, and the rest of the Home Assistant ecosystem, the [Automation Cookbook](https://beslain.gumroad.com/l/ha-automation-cookbook) has 25 ready-to-use YAML packages — including webhook bridges, notification patterns, and sensor-driven automations. Use code **LAUNCH50** for 50% off.

---

*This post is part of [The Automated Home](/) — practical Home Assistant guides from a 700+ entity production system.*