MQTT in Home Assistant einrichten: Mosquitto-Broker, Integration und erste Geräte

Für MQTT in Home Assistant (Stand November 2026) nutzen Sie am einfachsten die offizielle Mosquitto-Broker-App und fügen danach die MQTT-Integration hinzu. Der Broker, also der Vermittler zwischen Geräten und Home Assistant, muss laut Dokumentation das MQTT-Protokoll in Version 5 unterstützen. Quellen sind die Home-Assistant-Dokumentation zu dieser Integration und die Dokumentation der Mosquitto-App.

Erst der Postbote, dann die Post: Welcher Broker zu Home Assistant passt

Als Broker für MQTT empfiehlt die Home-Assistant-Dokumentation die offizielle Mosquitto-Broker-App. MQTT überträgt Nachrichten zwischen Maschinen nach dem Publish/Subscribe-Prinzip. Geräte veröffentlichen eine Nachricht zu einem Thema, andere abonnieren dieses Thema. Der Broker ist das Postamt dazwischen. Er nimmt jede Nachricht an. Dann stellt er sie allen zu, die das Thema abonniert haben.

Öffentliche Broker gibt es auch. Der eigene Broker ist laut Dokumentation aber die einfachste und privateste Option. Als empfohlene Einrichtungsmethode nennt die Doku die Mosquitto-App. Wer einen anderen Broker selbst betreibt, muss dessen Kompatibilität mit Home Assistant sicherstellen.

Zwei Grenzen gelten. Erstens muss der Broker das Protokoll in Version 5 beherrschen. Die meisten Broker tun das laut Dokumentation, auch die Mosquitto-App. Zweitens sind ActiveMQ und das RabbitMQ-MQTT-Plugin nicht unterstützt. Beim ActiveMQ-Broker nennt die Doku mindestens zwei Probleme, die das Zurückhalten von Nachrichten stören. Gemeint ist die Retention: Der Broker bewahrt die letzte Nachricht eines Themas für spätere Abonnierende auf.

Welche Hardware den Broker trägt, klärt der Ratgeber zur Home-Assistant-Hardware.

MQTT-Integration einrichten: Ein Klick, ein Benutzer und etwas Geduld

Die MQTT-Integration richten Sie ein, nachdem die Mosquitto-App installiert, gestartet und um einen Benutzer ergänzt ist. Die App installieren Sie laut Dokumentation unter Settings > Apps > Install app. Dort wählen Sie Mosquitto broker und klicken auf Install. Danach starten Sie die App. Jetzt heißt es warten. Laut Dokumentation dauert es ein paar Minuten, bis das App-Log das Ergebnis zeigt. Im Ernst, schauen Sie dort hinein. (Der Broker lässt sich nicht hetzen.)

Den Benutzer legen Sie im Home-Assistant-Frontend unter Settings > People > Users an, nicht im Configuration-Tab der App. Klingt einfach, ist es aber nicht: Fehlt die Option, muss in Ihrem Profil der Advanced Mode aktiv sein. Die Namen homeassistant und addons sind reserviert. Sie lassen sich nicht vergeben.

Die App hängt am Benutzersystem von Home Assistant. Deshalb taugen dessen Zugangsdaten auch für andere Clients des Brokers. Das spart Arbeit. Lokale Logins tragen Sie nur ein, wenn Sie sie ausdrücklich wollen. Dafür gibt es in der App-Konfiguration den Bereich logins.

Anschließend öffnen Sie Settings > Devices & services > Integrations. Laut der Dokumentation der Mosquitto-App erscheint MQTT dort oben als entdeckte Integration. Sie wählen sie aus, setzen bei Bedarf den Haken für MQTT Discovery und senden ab. Mehr braucht es nicht. Liegen noch alte MQTT-Einstellungen vor, entfernen Sie die alte Integration und starten Home Assistant neu, damit die neue erscheint.

Die Dokumentation zur MQTT-Integration nennt weitere Wege. Ein My-Button öffnet die Integrationsseite direkt. Manuell gehen Sie zu Settings > Devices & services, wählen unten rechts Add Integration und dann MQTT. Die Mosquitto-App lässt sich dabei gleich mitkonfigurieren. Home Assistant erzeugt dann einen sicheren Benutzernamen samt Passwort, weitere Aufmerksamkeit ist laut Doku nicht nötig. Das funktioniert auch, wenn Sie die App vorher selbst eingerichtet haben.

Bei einem selbst betriebenen Broker tragen Sie Hostname oder IP-Adresse, Port und, falls nötig, Benutzername und Passwort ein. Später ändern Sie das über Reconfigure in der Integration. Läuft Home Assistant noch gar nicht, hilft der Einsteiger-Guide.

Testlauf ohne Gerät: Eine Nachricht an sich selbst schicken

Den Broker testen Sie direkt in Home Assistant, ohne dass ein echtes Gerät angeschlossen ist. Öffnen Sie Settings > Devices & services und wählen Sie bei der Mosquitto-Integration Configure. Unter Publish a packet tragen Sie als Topic homeassistant/switch/1/power und als Payload ON ein. Das Topic ist die Adresse des Themas. Der Payload ist der Inhalt der Nachricht. Dann klicken Sie auf Publish.

Dieses Bild wurde mit KI generiertProviderhiggsfieldModellgpt_image_2_5 flare high 1k 16:9PromptIsometric 3D illustration of a MQTT test area: a floating interface panel on the left with a text field and a button labeled "Publish", a second panel on the right with a field containing "#" and a button labeled "Listen". In the center a small glossy server cube acts as the broker, with message packets shaped as little envelopes traveling along glowing lines from the left panel through the cube to the right panel, where they appear in a list. Soft pastel blue, teal and orange palette, light gray background, gentle shadows, clean minimal style, no people. No watermark, no signature.

Unter Listen to a topic geben Sie # ein, um alles zu sehen. Mit homeassistant/switch/# verfolgen Sie nur dieses Thema. Nach Start listening erscheinen die Nachrichten mit Uhrzeit, QoS und Retain-Angabe. QoS steht für die Dienstgüte der Zustellung. Retain zeigt, ob der Broker die Nachricht aufbewahrt.

Wer die Konsole mag, nutzt die Mosquitto-Kommandozeilentools. Laut Dokumentation stecken sie oft in einem Paket namens *-clients. Ein Beispiel für einen Broker auf localhost: mosquitto_pub -h 127.0.0.1 -t homeassistant/switch/1/on -m "Switch is ON". Mit mosquitto_sub -h 127.0.0.1 -v -t "homeassistant/#" lesen Sie alles mit, was unter dem Thema homeassistant ankommt.

Erste Geräte per Discovery: Das Gerät stellt sich selbst vor

Die Discovery von MQTT ist in Home Assistant standardmäßig aktiv und lässt Geräte ihre Konfiguration selbst mitbringen. Sie müssen also kaum etwas einrichten. (Ohne Discovery wird jedes neue Gerät zum Bastelprojekt, weil Sie es per YAML oder als Subentry anlegen.) Ein Subentry ist ein Eintrag in der Integration, der ein Gerät mit mindestens einer Entität enthält, also etwa einem Sensor oder Schalter.

Der Standard-Präfix des Discovery-Themas lautet homeassistant. Die Abonnements laufen standardmäßig mit Quality of Service Level 0. Präfix, Dienstgüte und der Schalter selbst lassen sich in den Optionen der Integration ändern.

Das Discovery-Thema folgt einem festen Muster: <discovery_prefix>/<component>/[<node_id>/]<object_id>/config. Die component ist etwa binary_sensor oder device. Node-ID und Objekt-ID dürfen laut Dokumentation nur Buchstaben, Ziffern, Unterstrich und Bindestrich enthalten. Best Practice ist es, die unique_id als Objekt-ID zu nehmen und die Node-ID wegzulassen.

Home Assistant kennt zwei Arten von Discovery-Nachrichten. Die Geräte-Discovery bündelt mehrere Komponenten in einer Nachricht. Die Einzelkomponenten-Discovery schickt pro Komponente eine eigene. Für Geräte mit mehreren Komponenten empfiehlt die Doku die Geräte-Discovery. Sie braucht weniger Nachrichten und überträgt die Geräteinformationen nur einmal.

Bei der Geräte-Discovery lautet die component im Thema device. Pflicht im Payload sind die Abschnitte dev für das Gerät und o für den Ursprung. Die einzelnen Komponenten stehen unter cmps. Jede braucht eine Plattform p und eine unique_id. Ein Temperatursensor erhält dort etwa die Geräteklasse temperature und die Einheit °C.

Nach dem Start von Home Assistant sind alle vorhandenen Geräte und Entitäten zunächst nicht verfügbar. Das bleibt so, bis eine Discovery-Nachricht verarbeitet wurde. Ein Gerät sollte deshalb die Birth-Nachricht abonnieren und darauf sein Discovery-Payload senden. Home Assistant schickt standardmäßig online und offline an homeassistant/status. Die Doku rät zu einer zufälligen Verzögerung, damit der Broker nicht unter hoher IO-Last leidet. Alternativ legt der Broker das Payload als retained Nachricht ab. Bei vielen Entitäten kann das ebenfalls hohe IO-Last erzeugen. Die Last-Will-Nachricht informiert andere Teilnehmende über einen getrennten Client, auch nach einem Absturz oder Netzwerkverlust.

Ein Beispiel für ein Gerät mit eigener MQTT-Schnittstelle liefert das Nuki-Entwicklerforum. Laut Beitrag vom 20. Oktober 2022 zur MQTT-API-Spezifikation 1.3 veröffentlicht ein Nuki-Gerät vor jeder Schließaktion eine kommagetrennte Liste im Topic lockActionEvent. Sie enthält unter anderem Aktion, Auslöser und Auth-ID. Gemeldet werden nur Aktionen, die tatsächlich ausgeführt werden sollen. Falsche Keypad-Codes tauchen nicht auf. Die Beta 3.5.2 enthielt laut Nuki am 28. Oktober 2022 den vollen Umfang von Version 1.3. Ein Forumsnutzer schrieb am 29. Juni 2023, er habe das Feature problemlos in seine Home-Assistant-Instanz eingebunden.

Wer Zigbee-Geräte anbinden will, findet im Vergleich ZHA und Zigbee2MQTT die Entscheidungshilfe.

Mit gesetzter unique_id lässt sich die entity_id nach dem Anlegen ändern. Die Änderung landet in der Entity Registry. Die entity_id entsteht beim ersten Laden. Existiert sensor.test schon, hängt Home Assistant einen Suffix an und vergibt sensor.test_2. Zum Entfernen einer Komponente senden Sie ein leeres, retained Payload an das Discovery-Thema.

Typische Stolpersteine und Grenzen: Wo der Betrieb zickt

Zertifikate, Zugriffsrechte und Zugangsdaten sind die Punkte, bei denen die Dokumentationen zu Home Assistant und zur Mosquitto-App ausdrücklich warnen. Fünf Fälle tauchen dort auf:

• Zertifikatsfehler: Erscheint die Meldung CERTIFICATE_VERIFY_FAILED, öffnen Sie in den Broker-Einstellungen Other settings und setzen Broker certificate validation auf Auto. Bei einem selbst signierten Zertifikat wählen Sie Custom und laden das CA-Zertifikat im PEM- oder DER-Format hoch. Passt der Hostname nicht zum Zertifikat, scheitert die Prüfung.
• Anonyme Logins: Die Mosquitto-App unterstützt sie nicht. Jede Verbindung braucht Benutzername und Passwort. Die Einstellung allow_anonymous true wirkt nicht.
• Zugriffsregeln: Aktivieren Sie ACLs, müssen die Benutzer homeassistant und addons uneingeschränkt lesen und schreiben dürfen. Sonst gibt es laut Doku Probleme. Dafür setzen Sie customize.active auf true und legen unter /share/mosquitto die Dateien acl.conf und accesscontrollist an.
• Neuinstallation: Bei der Einrichtung über die App erzeugt Home Assistant die Zugangsdaten und hält sie geheim. Sichern Sie vor einer Neuinstallation eine Kopie der App-Benutzeroptionen, etwa der zusätzlichen Logins. Danach aktualisiert die Integration das neue Passwort automatisch und verbindet sich neu.
• Offene Ports: Ohne Zertifikat läuft nur die unverschlüsselte Verbindung über Port 1883, für Websockets über 1884. Mit Zertifikat und Schlüssel kommen 8883 und 8884 hinzu, die unverschlüsselten Ports bleiben offen. Zum Abschalten leeren Sie die Ports in der Netzwerkkarte der App.

Die Debug-Option der App hilft bei der Fehlersuche. Dauerhaft eingeschaltet ist sie laut Doku keine gute Idee, weil sensible Informationen im Log landen. Unter Other settings der Integration stellen Sie außerdem Client-ID und Keep-Alive ein. Die Client-ID muss eindeutig sein. Der Keep-Alive-Standard liegt bei 60 Sekunden, mindestens sollten es 15 Sekunden sein.

Auch Geräte setzen Grenzen. Laut Jürgen Pansy im Nuki-Entwicklerforum vom 26. September 2023 ist MQTT nur über eine IP-Verbindung verfügbar, also per WLAN. Eine Bridge spart Energie, indem sie das WLAN des Schlosses abschaltet. Deshalb lassen sich Smart Lock 3 Pro, Bridge und MQTT nicht gleichzeitig nutzen.

Ihr nächster Schritt: App installieren, Benutzer anlegen, MQTT unter Integrations bestätigen und die Testnachricht mit dem Payload ON an homeassistant/switch/1/power senden. Offen bleibt beim Nuki die Zuordnung der Auth-ID zu Keypad-Nutzenden. Dafür blieb laut Nuki am 30. April 2023 nur Ausprobieren.