Home Assistant MQTT

Home Assistant talks to most of its devices over MQTT through the Mosquitto broker add-on. MQTT Viewer connects to that broker, as a desktop app or as a Home Assistant add-on, and shows every topic on it live.

Two ways to run it

  • Desktop app. Install MQTT Viewer on macOS, Windows or Linux and connect to the broker over the network.
  • Home Assistant add-on. Add https://github.com/mqtt-viewer/home-assistant-addon as an add-on repository, install MQTT Viewer from the store and open its web UI from the add-on page. Details on the Docker and Home Assistant page.

Connect to the Mosquitto broker

  1. Find the broker address and credentials. In Home Assistant open Settings, Add-ons, Mosquitto broker. The broker runs on the Home Assistant host, for example homeassistant.local, on port 1883. The add-on authenticates against Home Assistant users, so create one for MQTT or note an existing username and password.
  2. Install MQTT Viewer. Install the desktop app on macOS, Windows or Linux, or add the Home Assistant add-on from https://github.com/mqtt-viewer/home-assistant-addon and open its web UI from the add-on page.
  3. Add a connection. Create a connection with host homeassistant.local (or core-mosquitto from inside the add-on), port 1883 and the MQTT username and password. Connect.
  4. Add a homeassistant/# subscription. New connections subscribe to # and $SYS/# by default. Add homeassistant/# to keep the MQTT discovery configs in view.
  5. Watch state topics on the timeline. Select a state topic. The timeline shows every message with its time, and the compare tab shows what changed between one and the next.
  6. Publish a test payload. Publish to a command or state topic to confirm an automation fires, then resend it from publish history while you iterate.

What to look at

  • homeassistant/#: the MQTT discovery prefix. Devices publish retained config messages here that tell Home Assistant which entities to create. A missing entity starts here.
  • State topics: where a device reports its readings. The timeline shows whether a sensor publishes, how often and in what format. Tick a numeric field to chart it.
  • Availability topics: online or offline. A device stuck on offline explains most unavailable entities.
  • Retained configs from retired devices: a sensor removed months ago still exists while its discovery config is retained. Right-click its branch and clear the retained messages below it.

Coming from MQTT Explorer

The topic tree works the same way. MQTT Viewer adds a graph of the topics, a timeline per topic, retained-message cleanup, a status page for the broker and up to 10 connections at once. See the MQTT Explorer alternative page.

Frequently asked questions

What is the MQTT broker address in Home Assistant?

With the Mosquitto broker add-on, the broker runs on the Home Assistant host, for example homeassistant.local or its IP address, on port 1883. From inside another add-on the hostname is core-mosquitto.

How do you see all MQTT messages in Home Assistant?

Connect an MQTT client to the Mosquitto broker and subscribe to #. In MQTT Viewer every topic then appears in the live tree, and homeassistant/# holds the discovery configs that create entities.

Is there an MQTT Explorer add-on for Home Assistant?

MQTT Explorer is not among the official add-ons. MQTT Viewer ships as one: add https://github.com/mqtt-viewer/home-assistant-addon as a repository, install it from the add-on store and open its web UI from the add-on page. It connects to the Mosquitto add-on at core-mosquitto.

How do you remove a stale device from Home Assistant MQTT discovery?

Clear the retained config message under homeassistant/. In MQTT Viewer, right-click the device's branch and choose Clear retained messages below. Home Assistant removes the entities when the config is cleared.

The MQTT glossary covers retained messages, QoS and wildcards. For ESP-based sensors and custom firmware, see the ESP32 MQTT debugging guide.

MQTT Viewer is free and open source, and runs on macOS, Windows and Linux.

Download MQTT Viewer