Mosquitto MQTT Broker Setup with Zigbee2MQTT (September 2026)

Setting up Mosquitto MQTT broker with Zigbee2MQTT and Home Assistant is the backbone of a reliable local smart home. I have run this exact stack on three different installations, and the configuration pattern you are about to follow is the one I keep coming back to. Once you have the MQTT broker wired in, every Zigbee sensor, switch, and bulb in your home talks to Home Assistant without touching the cloud.

This guide walks you through the full process in 2026: installing the Mosquitto broker addon, creating secure user credentials, configuring the MQTT integration, deploying Zigbee2MQTT, and pairing your first device. I will also cover the Docker path for users who run Home Assistant Container, and a troubleshooting section that fixes the most common connection refused errors.

What Is MQTT and Why You Need a Mosquitto Broker?

MQTT is a lightweight publish/subscribe messaging protocol designed for small sensors and low-bandwidth devices. Instead of devices talking directly to each other, they publish messages to topics on a central broker, and any device that subscribes to those topics receives the updates. Mosquitto is the most popular open-source MQTT broker, and it is the de facto choice for Home Assistant setups.

You need a Mosquitto MQTT broker in Home Assistant because Zigbee2MQTT is not itself a broker. Zigbee2MQTT is a bridge that translates Zigbee radio traffic into MQTT messages. Without a broker, Zigbee2MQTT has nowhere to publish. The broker is the missing piece that turns a pile of Zigbee devices into a smart home network you can automate.

Running a local broker like Mosquitto also keeps your smart home off the cloud. Latency drops from hundreds of milliseconds to single-digit local network speeds, and your devices keep working even when your internet goes down. A local MQTT broker is the foundation of responsive, private, and reliable home automation.

Installing the Mosquitto Broker Addon in Home Assistant

The Mosquitto broker addon is the fastest way to get a working MQTT broker on Home Assistant OS or Home Assistant Supervised. The addon is maintained by the Home Assistant community and has been my go-to installation method for years.

1. Open your Home Assistant dashboard and click Settings in the sidebar.

2. Click Add-ons (on newer versions, go to Settings > Add-ons > Add-on Store).

3. Search for Mosquitto broker in the Add-on Store.

4. Click the official Mosquitto broker addon by Franck Nijhof.

5. Click Install and wait for the addon to download.

6. Do not start it yet. We need to configure users first.

If you cannot find the Mosquitto addon in your Add-on Store, your Home Assistant installation is likely running as a container (Docker) without the Supervisor. In that case, scroll down to the Docker installation section for the manual setup steps.

Creating MQTT User Credentials

You should never run Mosquitto with anonymous access enabled on a network. The MQTT broker needs a username and password so Zigbee2MQTT and Home Assistant can authenticate. The Mosquitto addon uses Home Assistant’s built-in user management, which makes creating MQTT user credentials straightforward.

1. Go to Settings > People in Home Assistant.

2. Scroll to the bottom and click Users in the bottom right (or open the Users tab).

3. Click Add User.

4. Enter a username like mqtt_user and a strong password.

5. Set the user as Administrator: Off and leave the user Enabled.

6. Click Create and then Save on the credentials screen.

Write down the username and password. You will use them in three places: the Mosquitto addon logins, the MQTT integration, and the Zigbee2MQTT configuration. If you cannot see the People option, you are running a Home Assistant install without user management, in which case username/password authentication requires manual configuration in mosquitto.conf.

Configuring the Mosquitto Addon

Now it is time to configure the Mosquitto addon with the user credentials you just created. The addon has a YAML configuration file that controls the broker behavior, including logins, listeners, and anonymous access.

1. In Settings > Add-ons, click the Mosquitto broker addon.

2. Open the Configuration tab.

3. Paste the following configuration, replacing the username and password with the ones you created:

logins:
  - username: mqtt_user
    password: YourStrongPasswordHere
anonymous: false
listeners:
  - type: tcp
    port: 1883

4. Click Save.

5. Switch to the Info tab and enable Start on boot and Watchdog.

6. Click Start and watch the Log tab to confirm the broker started without errors.

A successful startup log shows Opening ipv4 listen socket on port 1883. If you see Error: Unknown configuration option 'logins', you are running an older version of the addon and need to update. The anonymous: false line ensures no client can connect without proper credentials.

Understanding Port 1883 and the core-mosquitto Hostname

Port 1883 is the default MQTT port and it is what Home Assistant and Zigbee2MQTT use to talk to the broker. You do not need to change it for a standard setup. The reason most new users get confused is the hostname.

When the Mosquitto addon runs on Home Assistant OS, the broker is reachable from other addons at the hostname core-mosquitto. This is the magic hostname the addon registers automatically. You should not use localhost or your Home Assistant IP address when configuring Zigbee2MQTT or the MQTT integration from another addon. Use core-mosquitto for reliability, because it survives IP changes.

Adding the MQTT Integration to Home Assistant

With the broker running, the next step is to connect Home Assistant to it. The MQTT integration pulls in entities from your broker and makes them available to automations and dashboards.

1. Go to Settings > Devices & Services.

2. Click Add Integration in the bottom right.

3. Search for MQTT and select it.

4. Check Use the local broker box. Home Assistant will automatically use the Mosquitto addon running on core-mosquitto.

5. If you prefer manual configuration, uncheck the box and enter:

   • Broker: core-mosquitto

   • Port: 1883

   • Username: mqtt_user

   • Password: your password

6. Click Submit.

You should see Success! MQTT is now configured. If you get Connection failed: Connection refused, the broker is not running yet or your credentials are wrong. Go back to the addon Log tab and verify the broker started cleanly.

Verifying MQTT Is Working

The fastest way to test your MQTT setup is to publish a message from one tool and watch it arrive in another. MQTT Explorer is a desktop client that does exactly this. Download it from mqtt-explorer.com and connect using the same core-mosquitto, port 1883, username, and password you used in Home Assistant.

Once connected, you should see topics starting with homeassistant/ appearing as Zigbee2MQTT publishes device states. If MQTT Explorer can connect but Home Assistant says Connection refused, your Home Assistant credentials are wrong. If neither can connect, the broker is not running.

Installing the Zigbee2MQTT Addon

Zigbee2MQTT is the bridge that turns Zigbee radio traffic into MQTT messages. It supports hundreds of Zigbee devices from dozens of brands, and unlike proprietary hubs, it keeps everything local.

1. Go to Settings > Add-ons > Add-on Store.

2. Click the three-dot menu and choose Repositories.

3. Add this URL: https://github.com/zigbee2mqtt/hassio-zigbee2mqtt

4. Refresh the page and search for Zigbee2MQTT.

5. Click Install and wait for the addon to download.

6. Do not start it yet. We need to configure the coordinator path first.

If you run Home Assistant Container, the Zigbee2MQTT addon is not available either. You will need to install Zigbee2MQTT in a separate Docker container using the official image. The networking between the standalone Zigbee2MQTT container and the Mosquitto broker container needs to be configured carefully.

Configuring Zigbee2MQTT and Your Coordinator

Zigbee2MQTT needs to know two things: which USB device is your Zigbee coordinator, and where the MQTT broker is. The configuration is YAML, and the most common issue is the serial port path.

1. Plug in your Zigbee coordinator (a SONOFF Zigbee 3.0 USB Dongle Plus, SMLight SLZB-06, or similar).

2. In Home Assistant, go to Settings > System > Hardware > <three dots> > All Hardware and find the device path. It is usually /dev/ttyUSB0 or /dev/ttyACM0.

3. Open the Zigbee2MQTT addon Configuration tab.

4. Paste the following configuration, adjusting the serial port and MQTT broker:

mqtt:
  base_topic: zigbee2mqtt
  server: mqtt://core-mosquitto:1883
  user: mqtt_user
  password: YourStrongPasswordHere
serial:
  port: /dev/ttyUSB0
advanced:
  pan_id: 6754
  channel: 25

5. Click Save.

6. In the Info tab, enable Start on boot, Watchdog, and Show in sidebar.

7. Click Start.

The Zigbee2MQTT log should show MQTT publish: topic 'zigbee2mqtt/bridge/state', payload 'online' within 10 seconds. If you see Error: Failed to connect to MQTT server, scroll up to see the underlying error. The most common cause is the wrong username or password.

Choosing a Zigbee Channel

The default Zigbee channel is 11, but I prefer channel 25 because it sits well above the most-used WiFi channels (1, 6, and 11) in the 2.4 GHz band. Channel 25 reduces interference from your WiFi router and improves range for Zigbee devices. If you live in an apartment with many WiFi networks, channel 25 is the safest choice.

Connecting Your First Zigbee Device

With Zigbee2MQTT running, pairing your first device should take under a minute. Most modern Zigbee devices follow a simple pairing flow.

1. Open Zigbee2MQTT from the sidebar.

2. Click Permit join (All) in the top right. The icon turns green for 60 seconds.

3. Put your Zigbee device into pairing mode. For most sensors, this means holding a button for 5 seconds until an LED blinks rapidly.

4. Watch the Zigbee2MQTT log. You should see the device announce itself within a few seconds.

5. Once paired, the device appears in Home Assistant automatically through MQTT discovery.

Check Settings > Devices & Services > MQTT and you should see the new device with sensors, switches, or lights as the new entries. If the device does not appear, click Reconfigure on the MQTT integration to force a fresh discovery scan.

Docker Installation Alternative for Mosquitto

Docker users running Home Assistant Container cannot use the official Mosquitto addon. The good news is that running Mosquitto in Docker is just as reliable. Here is a tested Docker Compose setup.

services:
  mosquitto:
    image: eclipse-mosquitto:2.0
    container_name: mosquitto
    restart: unless-stopped
    ports:
      - "1883:1883"
      - "9001:9001"
    volumes:
      - ./mosquitto/config:/mosquitto/config
      - ./mosquitto/data:/mosquitto/data
      - ./mosquitto/log:/mosquitto/log

Create the mosquitto/config/mosquitto.conf file with this content:

persistence true
allow_anonymous false
password_file /mosquitto/config/passwd
listener 1883

Generate the password file by running inside the container: mosquitto_passwd -c /mosquitto/config/passwd mqtt_user. Enter your password twice. Then start the container with docker compose up -d.

From Home Assistant, point the MQTT integration at the host IP of the Docker host (for example, 192.168.1.50) instead of core-mosquitto. The magic hostname is only available inside the Supervisor ecosystem. Docker users need to use the host IP.

Troubleshooting Mosquitto Connection Refused Errors

Connection refused is the most common error when setting up the Mosquitto MQTT broker Home Assistant stack. Here are the four fixes that solve 90% of cases.

1. Broker not running: Open the Mosquitto addon Info tab and check if it says Running. If it is stopped, restart and watch the Log tab for errors.

2. Wrong hostname: Addons must use core-mosquitto. Docker and external installs must use the host IP.

3. Wrong credentials: The username and password are case-sensitive. Re-enter them carefully.

4. Old configuration.yaml entries: If you previously configured MQTT in YAML, remove the mqtt: block from configuration.yaml and restart Home Assistant.

For Docker users, the most common cause is forgetting to publish port 1883. Run docker ps and confirm the Mosquitto container has 0.0.0.0:1883->1883/tcp in the PORTS column. If the port is missing, your Docker Compose file is missing the ports section.

Optimizing Your Zigbee Network

Once everything works, a few tweaks will make your Zigbee network more reliable. Place your coordinator centrally in your home, away from WiFi routers and microwave ovens. Use channel 25 if you have WiFi interference. Add Zigbee routers (smart plugs with repeater function, or dedicated IKEA Tradfri signal repeaters) between distant devices.

Pair new devices near the coordinator first, then move them to their final location. Zigbee2MQTT remembers the network credentials, and the device will find the best router path automatically. For large homes, a mesh network of mains-powered Zigbee devices gives you far better coverage than relying on the coordinator alone.

Frequently Asked Questions

Wrapping Up the Mosquitto MQTT Broker Home Assistant Setup

Setting up Mosquitto MQTT broker with Zigbee2MQTT and Home Assistant is one of those projects that takes an afternoon but pays off every day. Once the broker is running and Zigbee2MQTT is paired, your smart home runs on a private local network that responds in milliseconds and keeps working without the internet.

The flow we covered covers every detail: installing the Mosquitto broker addon, creating user credentials, configuring the MQTT integration, deploying Zigbee2MQTT, and pairing your first device. We also covered the Docker path and the four most common connection refused errors. Save this guide for whenever you need to rebuild the stack, and share it with anyone who is tired of cloud-dependent smart home hubs.