MQTT and the Mosquitto Broker: What It's For and When You'll Need It

MQTT quietly powers a huge share of DIY and budget smart home devices, from ESPHome sensors to Tasmota-flashed plugs. This lesson explains what MQTT actually is, installs the Mosquitto Broker add-on that makes it work, and covers the security basics worth handling correctly from day one.

What this lesson doesn't do

This lesson doesn't flash a single ESPHome device or configure a specific MQTT sensor, that's the ESPHome module's job later in this course. It doesn't require you to understand MQTT deeply either, just enough to install Mosquitto correctly and know why it's there. Think of this lesson as laying plumbing before the fixtures arrive, MQTT itself does nothing visible on its own, its value only becomes obvious once real devices start using it.

Mosquitto Broker and the MQTT integration, two different things

MQTT support in Home Assistant actually involves two separate pieces working together. Mosquitto Broker is the add-on, the actual message-passing server that devices connect to and send data through. The MQTT integration, covered back in Lesson 2's vocabulary, is what connects Home Assistant itself to that broker, subscribing to the messages devices publish and turning them into entities you can see and use. You need both, the broker without the integration means Home Assistant never sees the messages passing through it, and the integration without a broker has nothing to connect to at all.

What MQTT actually is

MQTT is a lightweight messaging protocol built specifically for small, low-power devices communicating over a network, designed decades ago for industrial sensors and adopted enthusiastically by the DIY smart home world for exactly the same reasons, it's simple, efficient, and works reliably even on cheap WiFi microcontrollers with limited processing power. Devices publish messages to named topics, a temperature sensor might publish to home/livingroom/temperature, and anything subscribed to that topic, Home Assistant included, receives the message instantly. This publish-and-subscribe model is different from the request-and-response pattern most web-based integrations use, and it's part of why MQTT devices tend to report state changes with almost no perceptible delay at all, appearing in Home Assistant nearly the instant they happen.

When you'll actually need MQTT

If every device you own connects through an official integration, a name-brand Shelly, a Philips Hue bridge, most consumer smart plugs, you may genuinely never need MQTT directly, those integrations handle their own communication without it. MQTT becomes necessary the moment you build your own devices with ESPHome, later in this course, or flash budget hardware with Tasmota firmware, both of which speak MQTT natively as their primary way of talking to Home Assistant. Installing Mosquitto now, before you strictly need it, means it's simply ready and waiting when that first ESPHome project or Tasmota flash arrives, rather than an extra unfamiliar setup step slowing down that later lesson.

ESPHome, Tasmota, and MQTT

Worth a quick clarification here: ESPHome, covered in its own dedicated module later in this course, can actually connect to Home Assistant two different ways, its own native API, which is the default and doesn't require MQTT at all, or MQTT directly, useful in specific advanced setups. Tasmota, a separate firmware popular for flashing budget smart plugs and switches, relies on MQTT as its primary and most common integration path with Home Assistant. This course's ESPHome module defaults to the native API approach, so Mosquitto's role there is optional, while any Tasmota devices you encounter will very likely need it directly.

Why Mosquitto specifically

Several MQTT broker options exist, but Mosquitto, an open-source project maintained under the Eclipse Foundation, is by far the most widely used within the Home Assistant community, well-documented, lightweight, and available as an official add-on maintained by the Home Assistant team itself, unlike the community-maintained software covered in Lesson 5. It requires minimal resources, runs comfortably alongside everything else on any hardware route from Module 5, and its tight, official integration with Home Assistant means setup involves far fewer manual steps than configuring a general-purpose MQTT broker from scratch would.

Installing Mosquitto on HAOS

Open the Add-on Store from Settings, then Add-ons, search for Mosquitto broker, and install it exactly like any other official add-on from Lesson 3's flow. Start it, and enable Start on Boot, MQTT needs to be running continuously for any device to reliably reach it, an add-on that isn't running at boot means every MQTT device silently loses connection until you notice and restart it manually. No configuration is required at this stage beyond the defaults, the next two sections cover the two remaining setup steps, creating a dedicated MQTT user and adding the MQTT integration itself.

A dedicated MQTT user

Rather than reusing your main Home Assistant login for MQTT authentication, create a separate, dedicated user specifically for this purpose, under Settings, then People, then Users, with a strong, unique password. This dedicated account is what every MQTT device, ESPHome or Tasmota, will use to authenticate with Mosquitto, and keeping it separate from your own admin login means a compromised device credential never exposes your actual Home Assistant account at all. This small step, easy to skip in the moment, is exactly the kind of habit worth building now rather than retrofitting once you have a dozen devices already depending on a shared, less secure setup.

Adding the MQTT integration

With Mosquitto running, Home Assistant usually discovers it automatically and offers to add the MQTT integration through a notification, exactly the discovery flow from Lesson 2. Accept it, and when prompted for connection details, use localhost as the broker address since Mosquitto is running on the same server, along with the dedicated MQTT username and password created in the previous step. If discovery doesn't offer it automatically, add MQTT manually through Settings, then Devices and Services, the same manual-search path covered in Lesson 2, with identical connection details.

Testing the broker

Before your first real MQTT device arrives, it's worth confirming Mosquitto is actually working. Home Assistant's own Developer Tools, under Settings, then Developer Tools, then the MQTT tab, lets you manually publish a test message to any topic and watch it appear, a quick way to confirm the whole chain, broker, integration, authentication, functions correctly before troubleshooting a real device later. If a manually published test message appears immediately in that tab, Mosquitto and the MQTT integration are both configured correctly and ready for real devices.

Topics and MQTT Discovery

Topics are simply named channels messages flow through, structured hierarchically with slashes, home/livingroom/temperature being a typical example, and you'll rarely need to design these yourself, ESPHome and Tasmota both generate sensible topic structures automatically. Far more useful in practice is MQTT Discovery, a convention where a device publishes a small configuration message describing itself, its name, its type, its topic, and Home Assistant automatically creates the matching entity without any manual setup at all, essentially the MQTT equivalent of the discovery flow covered for regular integrations back in Lesson 2. Both ESPHome's default configuration and most modern Tasmota setups support MQTT Discovery out of the box, making the actual device-adding experience feel just as automatic as any other integration despite the different protocol underneath.

Retain and QoS, briefly

Two MQTT settings worth recognizing by name, even without needing to configure either manually right now: retain, which tells the broker to remember a topic's last message and immediately deliver it to anything that subscribes later, useful so a sensor's last known value isn't lost after a Home Assistant restart, and QoS, quality of service, which controls how strongly MQTT guarantees message delivery, at the cost of slightly more network overhead at higher levels. ESPHome and Tasmota both choose sensible defaults for these automatically, and this course won't ask you to adjust either manually, but recognizing the terms will help the occasional device documentation make sense later.

Security from the start

Mosquitto's default configuration on the Home Assistant add-on requires authentication out of the box, unlike some standalone MQTT setups that leave the broker wide open by default, but it's still worth double-checking Anonymous access is disabled in the add-on's own configuration tab, confirming the dedicated MQTT user from earlier is genuinely required for any device to connect. Since MQTT traffic stays entirely on your local network in this course's setup, not exposed to the internet, the main real risk is an unsecured device on your own WiFi rather than an outside attacker, one more reason the network segmentation covered back in Module 2 continues paying off here, long after the module that originally introduced it.

Startup order after a restart

Because Mosquitto and the MQTT integration are two separate pieces, a full Home Assistant restart occasionally has Home Assistant itself come online slightly before Mosquitto finishes starting, briefly showing MQTT entities as unavailable, the exact state discussed back in Lesson 1, before reconnecting automatically within moments. This is normal and self-resolving, not a sign of a real problem, and it's precisely the kind of transient unavailable state Lesson 1 asked you to recognize rather than panic over. If entities stay unavailable for more than a minute or two after a restart, that's the point worth actually investigating, likely starting with Mosquitto's own log tab.

Container on a NAS

On Home Assistant Container, Mosquitto runs as its own separate Docker container rather than an add-on, the official eclipse-mosquitto image being the standard choice, configured with its own password file and exposed on the standard MQTT port to your local network. The MQTT integration inside Home Assistant then connects to that container's address rather than localhost, everything else, the dedicated user, MQTT Discovery, testing through Developer Tools, works identically once that connection is established.

Diagnosing a broken connection

If a device won't connect to Mosquitto, work through this in order: confirm Mosquitto's own add-on shows as started and check its log tab for any obvious errors first. Confirm the device is using the correct broker address, your Home Assistant server's IP address, not localhost, since the device itself is a separate machine on your network. Confirm the username and password match the dedicated MQTT user exactly, a mistyped password is by far the most common single cause of MQTT connection failures. And confirm the device is genuinely on the same network and VLAN as Home Assistant, exactly the network reachability principle from Lesson 2 applying here too, working through these four checks in order resolves nearly every MQTT connection problem you're likely to encounter, without needing to reinstall Mosquitto or start over from scratch.

A real story: a Tasmota plug that seemed dead on arrival

One reader in this course's community flashed a budget smart plug with Tasmota, connected it to WiFi successfully, and then waited, and waited, for it to show up anywhere in Home Assistant, assuming discovery would eventually find it the way it had for every other device so far. It never did, because Tasmota doesn't announce itself the way locally-discovered integrations from Lesson 2 do, it simply publishes to MQTT and waits for something to be listening. Once Mosquitto was installed and the device's MQTT settings pointed at the broker's address with the dedicated MQTT user's credentials, the plug's entities appeared within seconds through MQTT Discovery, exactly as this lesson describes, no restart or troubleshooting needed beyond that one missing piece.

The lesson from that story is simple and worth remembering: if a device seems to connect to your WiFi fine but never appears in Home Assistant at all, not even as an ignored discovery, it's worth checking whether that device actually speaks MQTT before assuming something else is broken.

Why this course installs Mosquitto before you strictly need it

It might seem premature to install and configure a broker for devices you don't own yet, but the story above is exactly why this course front-loads it here rather than waiting. Setting up Mosquitto correctly, broker, dedicated user, integration, tested, takes roughly ten minutes when it's the only thing you're focused on in this lesson. Doing the same setup for the first time in the middle of an exciting first ESPHome build, or while troubleshooting a mysteriously silent Tasmota plug, turns a simple ten-minute task into a frustrating detour at exactly the moment you'd rather be enjoying a new project working.

Common questions

Do I need to install Mosquitto if I'm only using name-brand integrations? No, skip it entirely and revisit this lesson if and when you eventually build an ESPHome project or flash a Tasmota device. Does Mosquitto need internet access? No, it runs entirely on your local network and functions perfectly with no internet connection at all. Can I run more than one MQTT broker? Technically yes, but there's no good reason to for a typical home setup, one Mosquitto instance comfortably serves every MQTT device you're likely to own.

A short exercise before moving on

Install Mosquitto Broker now, create your dedicated MQTT user, add the MQTT integration, and publish a single test message through Developer Tools to confirm the whole chain works end to end. This takes perhaps ten minutes total and means MQTT is fully ready and waiting the moment the ESPHome module asks you to build your first custom device, rather than an unfamiliar detour in the middle of that later, more exciting lesson where your attention belongs on the project itself.

Key takeaways

With MQTT ready, Lesson 7 closes this module by bringing real structure, naming, areas, and documentation, to everything you've set up.