Home Assistant MQTT Setup: Broker, Integration & Discovery

MQTT is how Home Assistant talks to a huge range of devices: Zigbee2MQTT, Tasmota, ESPHome (optionally), Shelly, Frigate, OpenMQTTGateway and countless DIY sensors. Setting it up takes three pieces — a broker, the MQTT integration in Home Assistant and, ideally, MQTT discovery so devices appear automatically. This tutorial covers all three and shows how to test the setup with an MQTT client.

Step 1: Choose a broker — Mosquitto add-on or external

Home Assistant does not contain an MQTT broker itself; the integration is a client. You have two main options:

Option A: the Mosquitto broker add-on

1. Go to Settings → Add-ons → Add-on Store, search for Mosquitto broker and install it.
2. Start it and enable Start on boot and Watchdog.
3. Create a dedicated Home Assistant user for your devices (Settings → People → Users, e.g. mqtt-user). The add-on authenticates against Home Assistant users, so devices use those credentials. Do not reuse your admin account.
4. Home Assistant now shows a discovered MQTT integration under Settings → Devices & services. Click Configure and confirm.

Devices on your network connect to your Home Assistant host on port 1883 (and 8883 if you configure TLS in the add-on options).

Option B: an external broker

On Home Assistant Container or Core there is no add-on store, so run Mosquitto next to it — the easiest way is Mosquitto in Docker, or a package install as described in how to install Mosquitto. Remember that Mosquitto 2.x needs an explicit listener and authentication before other hosts can connect; the mosquitto.conf generator produces a working file, and securing Mosquitto covers users and ACLs.

Step 2: Configure the MQTT integration

For an external broker, add the integration manually: Settings → Devices & services → Add integration → MQTT. Enter:

• Broker — hostname or IP (in a shared Docker network, the container name such as mosquitto)
• Port — 1883, or 8883 for TLS (see MQTT ports)
• Username / Password — a broker user created for Home Assistant

Advanced options (enable them via Advanced mode in your user profile, then Configure → Re-configure MQTT) let you set TLS certificates, the client ID, the protocol version (3.1, 3.1.1 or 5), the discovery prefix and the birth and will messages. Broker connection details are configured in the UI; they can no longer be set in configuration.yaml.

Step 3: MQTT discovery

With discovery, a device announces itself by publishing a JSON config to a well-known topic, and Home Assistant creates the entity automatically — no YAML. The topic format is:

<discovery_prefix>/<component>/[<node_id>/]<object_id>/config

• discovery_prefix — homeassistant by default
• component — the entity type: sensor, binary_sensor, switch, light, cover, climate and so on
• node_id — optional grouping, usually the device ID
• object_id — an ID for this entity (letters, digits, _ and -)

Here is a temperature sensor. Publish it to homeassistant/sensor/garage_temp/config with the retain flag, so Home Assistant finds it again after a restart:

{
  "name": "Garage temperature",
  "unique_id": "garage_env_temp",
  "state_topic": "garage/env/state",
  "value_template": "{{ value_json.temperature }}",
  "unit_of_measurement": "°C",
  "device_class": "temperature",
  "state_class": "measurement",
  "device": {
    "identifiers": ["garage_env_01"],
    "name": "Garage environment sensor",
    "manufacturer": "DIY",
    "model": "ESP32 + BME280"
  }
}

unique_id makes the entity editable in the UI, and the device block groups entities under one device. The device then publishes its readings to the state topic:

{ "temperature": 21.4, "humidity": 48 }

Retained messages are essential here — read MQTT retained messages if the concept is new. Switches and lights additionally use a command_topic that Home Assistant publishes to when you toggle the entity.

Step 4: Test it with an MQTT client

You can simulate the whole device from a terminal with the Mosquitto clients (full flag reference in the mosquitto_pub/sub cheat sheet):

BROKER=homeassistant.local
AUTH="-u mqtt-user -P your-password"

mosquitto_pub -h $BROKER $AUTH -r -t 'homeassistant/sensor/garage_temp/config' -m '{
  "name": "Garage temperature",
  "unique_id": "garage_env_temp",
  "state_topic": "garage/env/state",
  "value_template": "{{ value_json.temperature }}",
  "unit_of_measurement": "°C",
  "device_class": "temperature",
  "device": { "identifiers": ["garage_env_01"], "name": "Garage environment sensor" }
}'

mosquitto_pub -h $BROKER $AUTH -t 'garage/env/state' -m '{"temperature": 21.4, "humidity": 48}'

The entity appears under Settings → Devices & services → MQTT. To watch everything Home Assistant and your devices exchange, subscribe to the discovery prefix:

mosquitto_sub -h homeassistant.local -u mqtt-user -P your-password -t 'homeassistant/#' -v

The MQTT integration page in Home Assistant also has a built-in Listen to a topic and Publish a packet tool. And to practise the discovery format without touching your home broker, publish the JSON above to a test topic on a public broker in the browser:

Try it in the online MQTT client

Common problems

• Integration cannot connect — wrong credentials, or the broker only listens on localhost. Check the broker log and the MQTT connection errors guide.
• Entity missing after a restart — the config was not retained, or the device does not republish on homeassistant/status = online.
• Entity shows "unknown" — the value_template does not match the payload, or nothing has been published to the state topic yet.
• Removing an entity — publish an empty retained message to its config topic (-r -n).

Frequently asked questions