MQTT is a lightweight publish/subscribe protocol. A broker sits in the middle: clients publish messages to topics, and other clients subscribe to those topics. Zigbee2MQTT, many Tasmota devices, ESPHome's MQTT client mode, and plenty of DIY sensors all speak it. Home Assistant can act as one of those clients once you point it at a broker.

The path Home Assistant recommends is the official Mosquitto broker app (formerly the Mosquitto add-on) on Home Assistant OS, plus the MQTT integration. This guide walks through that setup, how to create logins for your devices, how discovery works, and how to publish a test message so you know the pipe is open.

Broker and integration are two different things

People new to MQTT often mix up two pieces:

  • The broker is the server that stores and forwards messages. On Home Assistant OS that is usually the Mosquitto broker app.
  • The MQTT integration is Home Assistant's client. It connects to the broker, listens for discovery messages, and lets you publish from automations and the UI.

You need both. Running only the app does nothing useful in the UI until the integration is configured. Configuring the integration without a reachable broker fails to connect.

Home Assistant requires MQTT protocol version 5 on the broker. The official Mosquitto app supports that. The MQTT docs warn against ActiveMQ and the RabbitMQ MQTT plugin; both have issues that break retained messages.

Install Mosquitto and connect Home Assistant

There are two equally valid orders of operations.

Option A - let the integration install the app. Add the MQTT integration from Settings > Devices & services. When Home Assistant offers the official Mosquitto broker app, accept it. Home Assistant generates a username and password for its own connection and keeps them secret. You do not need to type them.

Option B - install the app first.

  1. Go to Settings > Apps > Install app.
  2. Find Mosquitto broker and install it.
  3. Start the app and wait a couple of minutes. Check the log until it looks clean.
  4. Go to Settings > Devices & services. MQTT should appear as a discovered integration. Select it, enable MQTT discovery if you want it (it is what Zigbee2MQTT and similar tools rely on), and submit.

If an old MQTT integration entry is still around from a previous broker, remove it and restart Home Assistant so the discovery of the new Mosquitto instance can appear.

When the official app and the integration are paired this way, reinstalling the app later regenerates the internal password. The integration updates itself and reconnects. Save a copy of any extra logins you added in the app options before you wipe the app, because those do not come back automatically.

Create a user for your devices

Home Assistant's own link to Mosquitto uses reserved names. Do not create users called homeassistant or addons; those belong to the internal ecosystem.

For Zigbee2MQTT, ESP devices, MQTT Explorer and anything else that must log in:

  1. Enable Advanced Mode in your Home Assistant profile if you do not see the Users menu.
  2. Go to Settings > People > Users and create a dedicated user. Prefer a user that exists only for MQTT, not your daily admin account.
  3. Point your devices at that username and password.

You can also define local users under the Mosquitto app's logins option, but you do not have to. Home Assistant users work with the broker with no extra broker-side configuration. Local logins entries are useful when you want a broker password that is not a Home Assistant login.

Anonymous connections are not supported by this app. Every client needs a username and password. Setting allow_anonymous true in a custom config will not work the way you expect.

Ports and TLS

By default Mosquitto listens on:

  • 1883 - plain MQTT
  • 1884 - MQTT over WebSockets
  • 8883 and 8884 - the same, with TLS, once you provide a certificate and key in the Home Assistant ssl folder and set certfile / keyfile in the app options

To shut off the plain ports, clear them on the app's network card so nothing listens there. Clients then have to use the TLS ports and must trust the server certificate.

require_certificate: true goes further: clients must present a certificate signed by the CA you put in cafile, and a username alone is not enough. Leave it false unless you know you need mutual TLS.

MQTT discovery

With discovery enabled (the default), devices announce themselves by publishing a JSON config to a topic under a discovery prefix. The default prefix is homeassistant. A typical single-component topic looks like:

homeassistant/sensor/<object_id>/config

or, for several entities on one device in one message:

homeassistant/device/<object_id>/config

The device sends the configuration. Home Assistant creates entities from it. That is how Zigbee2MQTT, Tasmota, OpenMQTTGateway and many others appear in Home Assistant with almost no YAML on the Home Assistant side. Tools with built-in discovery support are listed on the MQTT integration page; Zigbee2MQTT and ESPHome are on that list.

You can change or disable the discovery prefix under the MQTT integration options. Birth and last-will messages default to publishing online / offline on homeassistant/status. Devices that subscribe to that topic can republish their discovery payload when Home Assistant comes back, which avoids relying only on retained config messages at the broker.

Retained discovery messages survive a broker restart and make entities reappear quickly, but they also create "ghost" devices if a gadget is gone and nobody cleared the retained message. Prefer birth-triggered republishing when the device software supports it.

Test that messages flow

From the Home Assistant UI:

  1. Go to Settings > Devices & services, open the MQTT integration, and select Configure.
  2. Under Publish a packet, set a topic such as homeassistant/switch/1/power and a payload such as ON, then publish.
  3. Under Listen to a topic, enter # (everything) or a narrower filter like homeassistant/switch/#, then start listening. Your test message should show up with QoS and retain flags.

From a shell that has the Mosquitto clients package:

mosquitto_pub -h 127.0.0.1 -t homeassistant/switch/1/on -m "Switch is ON"
mosquitto_sub -h 127.0.0.1 -v -t "homeassistant/#"

Use the broker's real hostname or IP, and add -u / -P when the broker requires authentication (it does, on the official app).

Point a device at the broker

Whatever device you connect needs four facts:

  • Host: the Home Assistant machine's hostname or LAN IP (from another host on the LAN, not 127.0.0.1)
  • Port: 1883 for plain MQTT, or 8883 if you enabled TLS
  • Username and password: the Home Assistant user (or local login) you created
  • Optionally a client ID that is unique on the broker

For Zigbee2MQTT that goes in its mqtt section. For ESPHome, use the mqtt: component with the same fields when you are not using the native API. For Tasmota, set the MQTT parameters in its configuration menu. After the device connects, discovery (if the firmware supports it) should create entities without further YAML.

Access control lists

If every device shares one powerful user, a compromised gadget can publish anywhere on the broker. Mosquitto ACLs can limit each user to specific topics. The app docs show the pattern:

  1. Set customize.active to true and customize.folder to mosquitto.
  2. Put an acl.conf that points at an access control list file under /share/mosquitto/.
  3. In that list, give homeassistant and addons readwrite on #. Home Assistant expects those two users to have full access; locking them down breaks the integration and other apps.
  4. Add your own users with narrower topic rules.

The /share folder is reachable over Samba, or on the host under /usr/share/hassio/share.

When the connection fails

  • SSL certificate errors such as CERTIFICATE_VERIFY_FAILED: in the MQTT broker settings, open Other settings and set broker certificate validation to Auto for a publicly trusted cert, or upload your CA under Custom.
  • Protocol errors: confirm the broker speaks MQTT 5.
  • Discovery entities missing after a restart: the device must republish discovery (birth message) or you must have retained the config topic. Entities without a unique_id are not restored at startup until a new discovery message arrives.
  • Old YAML mqtt: broker settings fighting the UI: remove the outdated YAML broker config, remove the old integration entry, restart, and let discovery set up the Mosquitto app again.