Home Assistant MQTT: Connect Everything in Your Smart Home

Lightning fast

MQTT messages typically arrive in under 10 milliseconds on a local network. When a motion sensor fires, your lights respond instantly. No round-trip to some server in another country.

Universal connector

Zigbee2MQTT, Tasmota, ESPHome, Frigate, room-assistant, OwnTracks. Dozens of popular tools use MQTT to talk to Home Assistant. Set it up once and everything just connects.

Tiny footprint

MQTT was designed for constrained devices and unreliable networks. The Mosquitto broker uses about 10MB of RAM. It runs happily on a Raspberry Pi alongside Home Assistant without breaking a sweat.

You need MQTT if...

• You use Zigbee2MQTT to manage Zigbee devices (the most popular Zigbee option)
• You flash Tasmota firmware on cheap Wi-Fi devices like Sonoff switches
• You build custom sensors with ESPHome (though ESPHome also supports native API)
• You run Frigate NVR for AI-powered camera detection
• You want presence detection with room-assistant or monitor.sh
• You integrate OwnTracks for phone-based location tracking

You can skip MQTT if...

• You only use ZHA for Zigbee (it connects directly, no MQTT needed)
• Your devices all have native Home Assistant integrations (Hue, Shelly, IKEA, etc.)
• You stick to Matter/Thread devices only
• Your setup is small and you do not plan to expand much

That said, installing Mosquitto takes five minutes and costs nothing. Having it ready makes future expansions much easier.

Go to Settings → Add-ons → Add-on Store. Search for "Mosquitto broker" and click Install. This is the official add-on maintained by the Home Assistant team.

After installation, toggle Start on boot and Watchdog (auto-restart if it crashes). Then hit Start.

Go to Settings → People → Users and create a dedicated user for MQTT. Name it something like "mqtt" or "mqtt-user". Use a strong password.

The Mosquitto add-on automatically picks up Home Assistant user accounts for authentication. Any HA user can connect to MQTT with their credentials. Creating a dedicated user keeps things clean and makes it easier to track what is connecting.

Go to Settings → Devices & Services → Add Integration. Search for "MQTT" and select it. Home Assistant should auto-detect the running Mosquitto broker. Click Submit and you are done.

If auto-detection does not work, enter the broker address manually: localhost or core-mosquitto, port 1883, and the username/password you created.

Go to Developer Tools → MQTT (or Settings → Devices & Services → MQTT → Configure). You will see a "Listen to a topic" section. Subscribe to # (the wildcard that matches everything) and you should see messages flowing in.

You can also publish a test message. Set topic to test/hello and payload to Hello MQTT!. If it shows up in your subscription, everything is working.

Topic Structure

Topics use forward slashes to create a hierarchy, similar to file paths. A typical smart home setup might look like this:

home/living-room/temperature      → 22.3
home/living-room/humidity          → 45
home/bedroom/light/state           → ON
home/bedroom/light/brightness      → 80
zigbee2mqtt/motion-sensor/occupancy → true
frigate/events                     → {"type": "person", "camera": "front"}

Wildcards

MQTT supports two wildcards for subscribing to multiple topics at once:

• + matches one level: home/+/temperature gets temperature from every room
• # matches everything below: home/# gets all messages from all rooms and devices

Retained Messages and QoS

Two features that matter for smart home use:

• Retained messages stay on the broker. When Home Assistant restarts, it immediately gets the last known state of each device instead of waiting for the next update. Most smart home tools enable this by default.
• QoS (Quality of Service) controls delivery guarantees. QoS 0 is "fire and forget" (fastest). QoS 1 ensures delivery at least once. QoS 2 ensures exactly once delivery. For smart home use, QoS 0 or 1 works fine.

Zigbee2MQTT

The #1 reason people install MQTT

Zigbee2MQTT bridges your Zigbee devices to Home Assistant through MQTT. It supports over 4,000 devices, gives you more control than ZHA, and publishes all device data as clean MQTT topics. Install it as a Home Assistant add-on and point it at your Mosquitto broker.

Tasmota

Free your cheap Wi-Fi devices

Tasmota is open-source firmware you can flash onto many ESP8266/ESP32-based Wi-Fi devices. Sonoff switches, smart plugs, bulbs, power monitors. Once flashed, they communicate through MQTT instead of some random cloud server in China. Full local control, no app required.

ESPHome

Custom sensors and devices

ESPHome can use either its native API or MQTT to communicate with Home Assistant. The native API is simpler for most cases, but MQTT mode is useful when you want multiple systems to read the same sensor data, or when your ESP device is on a different network segment.

Frigate NVR

AI camera events via MQTT

Frigate is an AI-powered network video recorder that runs object detection on your security cameras locally. It uses MQTT to publish detection events (person detected, car in driveway, package at door). You can build powerful automations that react to what your cameras actually see.

OwnTracks

Privacy-focused location tracking

OwnTracks is a free phone app that shares your location over MQTT. Unlike Google or Apple location sharing, your data goes directly to your own Mosquitto broker. Perfect for presence-based automations like "turn on the heater when I am 10 minutes from home."

Room-Level Presence

Know which room you are in

Tools like room-assistant, ESPresense, and Bermuda use Bluetooth beacons and ESP32 boards to detect which room you are in. They publish room-level presence data over MQTT. This lets you build automations like "follow me" lighting that lights up whatever room you walk into.

1. Person Detection Alert

When Frigate detects a person on your front camera, send a notification with a snapshot:

automation:
  - alias: "Front door person alert"
    trigger:
      - platform: mqtt
        topic: "frigate/events"
        value_template: "{{ value_json.type }}"
        payload: "new"
    condition:
      - "{{ trigger.payload_json.after.label == 'person' }}"
      - "{{ trigger.payload_json.after.camera == 'front_door' }}"
    action:
      - service: notify.mobile_app
        data:
          title: "Someone at the front door"
          message: "Person detected at {{ now().strftime('%H:%M') }}"

2. Room-Based Lighting

Using ESPresense or room-assistant BLE presence, turn lights on when you enter a room:

automation:
  - alias: "Follow-me lights kitchen"
    trigger:
      - platform: mqtt
        topic: "espresense/rooms/kitchen/your_phone"
    condition:
      - "{{ trigger.payload_json.distance | float < 3 }}"
      - condition: state
        entity_id: sun.sun
        state: "below_horizon"
    action:
      - service: light.turn_on
        target:
          entity_id: light.kitchen
        data:
          brightness_pct: 80

3. Zigbee Button Actions

React to Zigbee2MQTT button presses with different actions for single, double, and long press:

automation:
  - alias: "Bedside button controls"
    trigger:
      - platform: mqtt
        topic: "zigbee2mqtt/bedside_button/action"
    action:
      - choose:
          - conditions: "{{ trigger.payload == 'single' }}"
            sequence:
              - service: light.toggle
                entity_id: light.bedroom
          - conditions: "{{ trigger.payload == 'double' }}"
            sequence:
              - service: scene.turn_on
                entity_id: scene.bedroom_night
          - conditions: "{{ trigger.payload == 'hold' }}"
            sequence:
              - service: light.turn_off
                entity_id: all

4. Tasmota Power Monitoring

Get notified when your washing machine finishes its cycle based on power consumption:

automation:
  - alias: "Washing machine done"
    trigger:
      - platform: mqtt
        topic: "tele/washing_plug/SENSOR"
    condition:
      - "{{ trigger.payload_json.ENERGY.Power | float < 5 }}"
      - condition: state
        entity_id: input_boolean.washing_running
        state: "on"
    action:
      - service: notify.mobile_app
        data:
          title: "Laundry done! 🧺"
          message: "Your washing machine has finished."
      - service: input_boolean.turn_off
        entity_id: input_boolean.washing_running

5. Cross-System Notifications

Send data from Home Assistant to other systems like Node-RED, Grafana, or custom scripts:

automation:
  - alias: "Publish daily energy summary"
    trigger:
      - platform: time
        at: "23:59:00"
    action:
      - service: mqtt.publish
        data:
          topic: "home/energy/daily_summary"
          payload_template: >
            {"date": "{{ now().strftime('%Y-%m-%d') }}",
             "total_kwh": {{ states('sensor.daily_energy') }},
             "cost": {{ (states('sensor.daily_energy') | float * 0.25) | round(2) }}
            }
          retain: true

Enable Persistence

By default, the HA add-on enables persistence, which saves retained messages to disk. This means your device states survive broker restarts. If you are running Mosquitto manually, add this to your config:

persistence true
persistence_location /mosquitto/data/

Enable Logging (Temporarily)

When debugging, enable verbose logging to see all messages flowing through the broker. In the add-on configuration, set the log level to "debug". Remember to set it back to "warning" after, as debug logging can fill up your disk.

WebSocket Support

If you want to use MQTT from a web browser (for custom dashboards or debugging tools), enable the WebSocket listener. The HA add-on exposes port 1884 for WebSocket connections by default. For manual installs:

listener 1883
protocol mqtt

listener 1884
protocol websockets

"Connection Refused" or "Unable to Connect"

• Check that the Mosquitto add-on is actually running (green indicator in the add-on page)
• Verify the broker address. Use core-mosquitto for the HA add-on, or your server IP for external installs
• Make sure port 1883 is not blocked by your firewall
• Double-check the username and password. The MQTT user must exist in Home Assistant's user list

Devices Show as "Unavailable"

• The device might have gone offline. Check its power and Wi-Fi connection
• Look for "Last Will and Testament" (LWT) messages. MQTT devices publish an "offline" message when they disconnect. Check the device's availability topic
• Restart the device. Many MQTT devices need a fresh connection after a broker restart
• Check if retained messages are cleared. If you cleared the MQTT database, devices will show unavailable until they publish new data

Duplicate Entities or Ghost Devices

• This usually happens when MQTT discovery creates a new entity after a config change. Delete the old entity from Settings → Devices & Services → MQTT → Entities
• If you renamed a device in Zigbee2MQTT, the old entity might still exist. Remove it manually
• To clear all retained discovery messages: use MQTT Explorer (a desktop app) to delete topics under homeassistant/

High CPU or Memory Usage

• Check for message loops. A misconfigured automation can publish to a topic it also subscribes to, creating infinite loops
• Reduce logging verbosity. Debug-level logging generates enormous amounts of data
• If you have hundreds of devices, consider increasing the max_inflight_messages setting for better throughput

MQTT Explorer

The best desktop app for inspecting your MQTT broker. Shows all topics in a tree view, lets you publish test messages, monitor traffic in real-time, and delete retained messages. Free and open source. Available for Windows, Mac, and Linux.

mosquitto_sub / mosquitto_pub

Command-line tools that come with Mosquitto. Quick way to subscribe to topics or publish messages for testing. Install with apt install mosquitto-clients on Linux.

HA Developer Tools

Built right into Home Assistant. Go to Developer Tools → MQTT to subscribe to topics, publish messages, and test your configuration without installing anything extra.