Home Assistant MQTT Setup: Complete Guide

If you have ever wondered why your Shelly relay, Sonoff switch, or Tasmota-flashed socket disappears from Home Assistant the moment the Wi-Fi hiccups, the answer often comes down to one thing: home assistant mqtt setup. MQTT is a lightweight publish-subscribe protocol designed specifically for unreliable networks and low-power devices, and once it is running in Home Assistant you gain rock-solid, near-instant control over a huge range of hardware. This guide covers everything from installing the broker to seeing your first device auto-discovered.

What Is MQTT and Why Does It Matter?

MQTT (Message Queuing Telemetry Transport) was originally developed for satellite telemetry in the late 1990s and later adopted as an ISO standard. At its core it is a broker-and-client model: devices publish messages to named topics, and other devices or software subscribe to those topics. The broker — Mosquitto in most home setups — sits in the middle and routes traffic.

For smart home use this model has three big advantages:

• Lightweight. MQTT packets are tiny, so battery-powered sensors can stay asleep between readings and still push data reliably.
• Fast. Round-trip latency from a wall switch to Home Assistant is typically under 50 ms on a local network.
• Local. Everything stays on your LAN — no cloud dependency, no privacy concerns, no subscription fees.

If you are new to Home Assistant itself, the Home Assistant UK setup guide covers installation from scratch before you add MQTT.

Install the Mosquitto Broker Add-on

Home Assistant OS and Home Assistant Supervised users can run Mosquitto as an official add-on, which means no command-line configuration and automatic integration with the supervisor.

1. In Home Assistant, go to Settings → Add-ons → Add-on Store.
2. Search for Mosquitto broker and select the result published by the Home Assistant team.
3. Click Install and wait for the download to complete.
4. On the add-on's Info tab, enable Start on boot and Watchdog, then click Start.

Mosquitto is an open-source MQTT broker that implements MQTT protocol versions 5.0, 3.1.1, and 3.1, making it compatible with every smart home device you are likely to encounter. Home Assistant requires your broker to support MQTT protocol version 5 — the official add-on meets this requirement out of the box.

You do not need to edit the add-on's configuration YAML for a basic setup. Home Assistant will generate secure credentials automatically when you set up the integration in the next step.

Configure the MQTT Integration in Home Assistant

With the broker running, wire Home Assistant to it via the MQTT integration:

1. Go to Settings → Devices & Services → Add Integration.
2. Search for and select MQTT.
3. Home Assistant detects the running Mosquitto add-on and offers to configure automatically — click Submit.
4. If you are connecting to an external broker instead, enter the broker's IP address, port (default 1883), and your credentials manually.

Once the integration is added, a new MQTT entry appears in Devices & Services. Clicking Configure lets you adjust the discovery prefix, birth messages, and last-will settings without editing YAML.

For more must-have add-ons to pair with MQTT, see our roundup of the best Home Assistant add-ons.

Test with MQTT Explorer

Before connecting real devices, confirm the broker is working with MQTT Explorer — a free, open-source desktop app (Windows, macOS, Linux) that shows every topic on your broker in a live tree view. The latest stable release is version 1.13.0.

1. Download MQTT Explorer from mqtt-explorer.com.
2. Create a new connection: enter your Home Assistant IP address as the host, port 1883, and the MQTT username and password Home Assistant generated (found in the Mosquitto add-on's Configuration tab under logins).
3. Click Connect. If Mosquitto is healthy you will immediately see the homeassistant/ topic tree populate.

You can also publish a test message from MQTT Explorer to confirm two-way communication, then watch Home Assistant's developer tools log to verify it arrived.

Connect Smart Home Devices via MQTT

MQTT is supported natively by three of the most popular DIY-friendly hardware families:

Shelly Devices

Modern Shelly devices (Plus and Pro ranges) have built-in MQTT support via their web UI. Open the device's interface, go to Settings → MQTT, enable MQTT, and enter your broker's IP, port, username, and password. Shelly Gen2 and later devices also support MQTT auto-discovery. The Shelly Plus 1 (available on Amazon.co.uk, prices vary by retailer) is a popular choice for converting standard light switches to smart ones without replacing the switch plate.

Sonoff Devices with Tasmota

Many Sonoff devices — including the compact Sonoff Mini R4 (Amazon.co.uk, prices vary) — can be flashed with the open-source Tasmota firmware, which adds MQTT support and removes the cloud dependency entirely. After flashing, open the Tasmota web interface, go to Configuration → Configure MQTT, and enter your broker details.

Tasmota Firmware

Tasmota runs on dozens of ESP8266 and ESP32-based devices. Once MQTT is configured, entering SetOption19 0 in the Tasmota console enables full Home Assistant auto-discovery. Tasmota version 9.2 or later is required; version 10.1.0 or later is recommended for the best experience.

MQTT Auto-Discovery in Home Assistant

MQTT auto-discovery is enabled by default when you set up the MQTT integration. Home Assistant subscribes to the homeassistant/# topic tree and listens for discovery payloads. When a compatible device comes online it publishes a small JSON config message to a topic like:

homeassistant/switch/living_room_socket/config

Home Assistant reads that payload and automatically creates the entity — no YAML, no restart. The discovery prefix (homeassistant by default) can be changed in the MQTT integration's options.

For devices to reliably appear after a Home Assistant restart, they should either publish their discovery message with the retain flag set (so the broker stores and replays it) or subscribe to the homeassistant/status birth topic and re-publish discovery payloads when they see an online message.

Tasmota, Shelly Gen2 firmware, and ESPHome all handle this correctly out of the box, which is why they pair so cleanly with Home Assistant's MQTT integration.

Troubleshooting Tips

• Entity not appearing? Open MQTT Explorer and check whether the device is publishing to the expected topic. If the topic is missing, the device has not connected to the broker — double-check IP, port, and credentials on the device side.
• Broker rejects connections? Confirm the Mosquitto add-on is running and that you are using the correct Home Assistant-generated credentials. The add-on log (visible in the add-on's Log tab) shows authentication errors in real time.
• Entities disappear after restart? Ensure retained messages are enabled on the device or that it re-publishes discovery payloads on Home Assistant's birth message. In MQTT Explorer you can verify whether a topic has the retain flag set.
• Wrong state values? Check the value_template in the entity's MQTT configuration. Tasmota uses POWER as the state key; Shelly uses a different schema — consult the device's documentation for the exact payload format.

Related: Zigbee2MQTT setup guide, Node-RED automations in Home Assistant, and IoT VLAN for Home Assistant.