How to Set Up an MQTT Broker in Home Assistant
To set up an MQTT broker in Home Assistant, the simplest path is to install the official Mosquitto broker add-on, create a dedicated Home Assistant user for your devices to log in with, and then add the MQTT integration so Home Assistant can talk to the broker. On a standard Home Assistant OS or Supervised install, this takes about ten minutes and needs no command line. Below we walk through each step, explain why MQTT is worth adding, and cover the connection details you will hand to devices and add-ons like Zigbee2MQTT.
What an MQTT broker actually does
MQTT (Message Queuing Telemetry Transport) is a lightweight publish-and-subscribe protocol built for low-power devices and unreliable networks. Instead of devices talking directly to each other, they all connect to a central server called a broker. A device publishes a message to a named channel (a "topic"), and anything subscribed to that topic receives it. Home Assistant subscribes to the topics your devices publish, and publishes commands back to topics your devices listen on.
You need a broker because Home Assistant is not one by itself — it is an MQTT client. Popular projects such as Zigbee2MQTT and Tasmota firmware, plus countless DIY sensors, all assume a broker is sitting in the middle. Running one locally also keeps this traffic off the cloud, which fits nicely if you are trying to move your smart home off the cloud.
Before you start
This guide assumes you already have Home Assistant running. If you don't yet, see our guides on how to install Home Assistant or Home Assistant on a Raspberry Pi. The add-on method below requires Home Assistant OS or a Supervised install, because those are the versions that support add-ons. If you run Home Assistant Core in a Python virtual environment or a bare Docker container, you'll install Mosquitto separately (covered briefly in the FAQ).
Step 1: Install the Mosquitto broker add-on
Mosquitto is a mature, open-source broker maintained under the Eclipse Foundation, and the Home Assistant team packages it as an official add-on. To install it:
- Open Settings → Add-ons in Home Assistant.
- Click the Add-on Store button (bottom right).
- Search for Mosquitto broker and open it — look for the one marked as an official add-on.
- Click Install. This pulls the container image and can take a minute or two.
- Once installed, enable Start on boot and Watchdog, then click Start.
Check the add-on's Log tab. A healthy broker prints startup lines confirming the Mosquitto version and that it is running. If you're new to add-ons in general, our Home Assistant add-ons explainer covers how they work and where they live.
Step 2: Create a dedicated MQTT user
The Mosquitto add-on authenticates MQTT clients against Home Assistant's own user accounts. That's convenient, but you should not hand your personal admin login to every sensor. Instead, create a separate account whose only job is MQTT.
- Go to Settings → People and open the Users tab (you may need to enable advanced mode on your profile to see it).
- Add a new user — for example, username
mqtt-userwith a strong password. - You can leave it as a non-admin user. Record the username and password; devices will use these to log in.
Step 3: Add the MQTT integration
With the broker running, tell Home Assistant to connect to it:
- Go to Settings → Devices & Services.
- Click Add Integration and search for MQTT.
- Home Assistant usually detects the local Mosquitto add-on automatically and offers to configure it — accept that.
- If prompted for connection details, enter the broker address
core-mosquitto, port1883, and the username and password from Step 2.
The core-mosquitto hostname is how add-ons and integrations reach the broker inside Home Assistant's internal network. External devices on your LAN use your Home Assistant machine's IP address instead (also on port 1883).
- 1Install the Mosquitto broker add-on and start it
- 2Create a dedicated non-admin user for MQTT logins
- 3Add the MQTT integration and point it at core-mosquitto:1883
- 4Connect a device or test with MQTT publish/listen
Step 4: Test the connection
Before connecting real hardware, confirm messages flow. The MQTT integration includes simple debug tools:
- On Settings → Devices & Services, open the MQTT integration and click Configure.
- Use Listen to a topic, enter
#(a wildcard for all topics), and click Start listening. - Use Publish a packet to send a test message to a topic like
test/hellowith a short payload. - You should see your published message appear in the listen window — proof the broker is relaying traffic.
Where MQTT fits with the rest of your setup
A very common reason beginners set up a broker is Zigbee. Zigbee2MQTT, one of the two main ways to run Zigbee in Home Assistant, publishes all device data over MQTT and therefore requires a broker — whereas the alternative, ZHA, does not. If you're deciding between them, our comparison of ZHA vs Zigbee2MQTT explains the trade-offs, and our roundup of Zigbee USB coordinators covers the hardware side.
| Detail | For add-ons & integrations | For external LAN devices |
|---|---|---|
| Broker address | core-mosquitto | Home Assistant's IP (e.g. 192.168.1.x) |
| Port | 1883 | 1883 (8883 for TLS) |
| Username / password | Your dedicated MQTT user | Same MQTT user |
| Typical clients | Zigbee2MQTT add-on | Tasmota devices, ESP sensors |
Frequently asked questions
Do I need a broker if I only use ZHA or Matter?
No. ZHA (the built-in Zigbee integration) and Matter both talk to Home Assistant directly and don't use MQTT. You only need a broker if a device, add-on, or firmware you want to run specifically communicates over MQTT — such as Zigbee2MQTT, Tasmota, or many DIY ESP-based sensors.
What's the difference between the broker and the MQTT integration?
The broker (Mosquitto) is the server that relays messages between all clients. The MQTT integration is Home Assistant's client connection to that server. You install the broker once, then the integration lets Home Assistant publish and subscribe. Both are needed for a working setup.
Can I run Home Assistant Core without add-ons and still use MQTT?
Yes, but you install Mosquitto yourself — for example via your operating system's package manager or a separate Docker container — and then point the MQTT integration at that broker's IP address and port. The integration steps are identical; only the broker installation differs. If you're unsure which install type you have, our overview of what Home Assistant is explains the editions.
My devices connect but I see no data — what's wrong?
The usual culprits are a wrong username or password, pointing a device at core-mosquitto instead of your Home Assistant IP (that hostname only works inside Home Assistant), or a mismatched topic. Use the integration's "Listen to a topic" tool with the # wildcard to see whether the device is publishing anything at all; silence there points to authentication or network issues rather than a Home Assistant config problem.
