MQTT Broker URL Format: mqtt://, mqtts://, ws:// und wss:// erklärt

Eine MQTT Broker URL teilt einem Client mit, welchen Transport er nutzen, welchen Host er erreichen, welchen Port er öffnen und, bei WebSockets, welchen Pfad er anfragen soll. Am Ende dieses Leitfadens können Sie jede MQTT-URL lesen und schreiben, das passende Schema und den passenden Port für Ihre Umgebung wählen und die Handvoll Fehler vermeiden, die hinter den meisten „Verbindung klappt nicht“-Meldungen stecken.

Aufbau einer MQTT Broker URL

Eine vollständige MQTT-URL sieht so aus:

wss://broker.connectmq.com:8084/mqtt
\_/   \__________________/ \__/\___/
 |            |              |    |
scheme       host           port path

• Schema wählt den Transport: rohes TCP oder WebSocket, unverschlüsselt oder verschlüsselt.
• Host ist der DNS-Name oder die IP-Adresse des Brokers.
• Port ist der Ort, an dem der Broker für diesen Transport lauscht.
• Pfad gilt nur für WebSocket-Schemata; er ist der HTTP-Pfad, an den die WebSocket-Upgrade-Anfrage geht.

Zugangsdaten und Client ID sind meist nicht Teil der URL. Manche Bibliotheken akzeptieren mqtt://user:pass@host, doch sie als separate Optionen zu übergeben, ist übersichtlicher und verhindert, dass Passwörter in Logs landen.

Die vier Schemata

In Java- und Eclipse-Paho-Clients begegnen Ihnen auch tcp:// und ssl://; sie entsprechen mqtt:// und mqtts://. Manche Werkzeuge akzeptieren für die verschlüsselte TCP-Variante zudem tls://.

Die Ports 1883 und 8883 sind bei der IANA für MQTT registriert. WebSocket-Ports sind nicht standardisiert, weshalb Sie sie immer in der Dokumentation des Brokers nachsehen müssen. Unser Leitfaden zu MQTT-Ports behandelt die Hintergründe ausführlicher.

Das richtige Schema wählen

• Geräte und Server: Verwenden Sie mqtts:// auf 8883. Das ist die effizienteste verschlüsselte Option.
• Browser: Sie können keine rohen TCP-Sockets öffnen und müssen daher wss:// verwenden. Über HTTPS ausgelieferte Seiten lehnen ws:// als Mixed Content ab. Siehe MQTT über WebSocket.
• Restriktive Firmen- und Werksnetze: Ist ausgehender Verkehr auf 8883 gesperrt, kommt wss:// manchmal durch Proxys, die WebSockets verstehen. In OT-Netzen nach einem Zonenkonzept wie IEC 62443 klären Sie Port und Ziel besser mit der IT/OT-Sicherheit, statt Umwege zu suchen.
• Lokale Tests: mqtt:// auf 1883 ist in einem Labornetz oder gegen den öffentlichen MQTT-Broker in Ordnung, niemals jedoch für Zugangsdaten über das Internet.

Der WebSocket-Pfad ist entscheidend

Der mit Abstand häufigste WebSocket-Fehler ist ein fehlender oder falscher Pfad. Broker liefern MQTT über WebSocket auf einem bestimmten HTTP-Pfad aus, und /mqtt ist die verbreitetste Konvention. ConnectMQ verwendet /mqtt sowohl auf 8083 als auch auf 8084. Wenn Sie sich ohne Pfad mit wss://broker.connectmq.com:8084 verbinden, geht die Upgrade-Anfrage an / und schlägt fehl, meist mit einem wenig aussagekräftigen Close-Event.

Beispiele für MQTT Broker URLs nach Client

Node.js und Browser mit MQTT.js

MQTT.js erwartet eine URL plus ein Options-Objekt. Das funktioniert in Node.js mit mqtts:// und im Browser mit wss://.

import mqtt from "mqtt";

const isBrowser = typeof window !== "undefined";
const url = isBrowser
  ? "wss://broker.connectmq.com:8084/mqtt"
  : "mqtts://broker.connectmq.com:8883";

const client = mqtt.connect(url, {
  clientId: "YOUR_CLIENT_ID",
  username: "YOUR_USERNAME",
  password: "YOUR_PASSWORD",
  protocolVersion: 5,
  keepalive: 60,
  reconnectPeriod: 2000,
});

client.on("connect", () => {
  console.log("Connected to", url);
  client.subscribe("demo/#", { qos: 1 });
  client.publish("demo/hello", "hi from MQTT.js", { qos: 1 });
});

client.on("message", (topic, payload) => {
  console.log(topic, payload.toString());
});

client.on("error", (err) => console.error("MQTT error:", err.message));

Python mit paho-mqtt

Paho parst keine URLs, sondern erwartet Host, Port und Transport getrennt. Eine kleine Hilfsfunktion zerlegt eine URL in diese Teile.

import ssl
from urllib.parse import urlparse

import paho.mqtt.client as mqtt

DEFAULT_PORTS = {"mqtt": 1883, "mqtts": 8883, "ws": 8083, "wss": 8084}


def client_from_url(url: str, client_id: str, username=None, password=None):
    u = urlparse(url)
    scheme = u.scheme.lower()
    transport = "websockets" if scheme in ("ws", "wss") else "tcp"
    client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id=client_id,
                         transport=transport, protocol=mqtt.MQTTv5)
    if transport == "websockets":
        client.ws_set_options(path=u.path or "/mqtt")
    if scheme in ("mqtts", "wss"):
        client.tls_set(cert_reqs=ssl.CERT_REQUIRED)
    if username:
        client.username_pw_set(username, password)
    port = u.port or DEFAULT_PORTS[scheme]
    return client, u.hostname, port


def on_connect(client, userdata, flags, reason_code, properties):
    print("Connected:", reason_code)


client, host, port = client_from_url(
    "wss://broker.connectmq.com:8084/mqtt",
    client_id="YOUR_CLIENT_ID",
    username="YOUR_USERNAME",
    password="YOUR_PASSWORD",
)
client.on_connect = on_connect
client.connect(host, port, keepalive=60)
client.loop_forever()

Kommandozeile

Die Mosquitto-Werkzeuge erwarten Host und Port statt URLs, neuere Versionen akzeptieren aber auch -L mit einer URL:

# Unverschlüsseltes TCP gegen den öffentlichen Broker
mosquitto_sub -h broker.connectmq.com -p 1883 -i cli-sub-r4t9 -t 'connectmq/demo/r4t9/#' -v

# TLS mit Zugangsdaten, in URL-Form
mosquitto_sub -L mqtts://YOUR_USERNAME:YOUR_PASSWORD@broker.connectmq.com:8883/devices/# \
  -i YOUR_CLIENT_ID --capath /etc/ssl/certs -v

Bei -L ist das Pfadsegment nach dem Port das Topic, nicht ein WebSocket-Pfad.

Arduino und ESP32

Embedded-Bibliotheken wie PubSubClient erwarten Host und Port ebenfalls getrennt. Ob die Verbindung verschlüsselt ist, hängt vom Netzwerk-Client ab, WiFiClient für 1883 oder WiFiClientSecure für 8883, nicht von einem URL-Schema. Das Tutorial ESP32 mit Cloud-MQTT-Broker zeigt das vollständige TLS-Setup.

Node-RED

Node-RED läuft häufig auf Edge-Gateways in der Fertigung, um Daten von SPS oder OPC-UA-Servern an den Broker weiterzureichen. Setzen Sie im Konfigurationsknoten mqtt-broker den Server auf broker.connectmq.com, den Port auf 1883 oder 8883 und aktivieren Sie für 8883 „Use TLS“. Für WebSockets tragen Sie stattdessen die vollständige URL wss://broker.connectmq.com:8084/mqtt in das Feld Server ein.

Checkliste zur Fehlerbehebung

Wenn eine Verbindung fehlschlägt, prüfen Sie Folgendes der Reihe nach:

1. Schema und Port passen zusammen. mqtts:// auf 1883 oder mqtt:// auf 8883 schlägt fehl oder hängt.
2. Der WebSocket-Pfad ist vorhanden. /mqtt bei broker.connectmq.com.
3. Hostname statt IP bei TLS. Das Zertifikat ist für den Hostnamen ausgestellt; eine Verbindung per IP besteht die Prüfung nicht.
4. Kein ws:// von HTTPS-Seiten. Browser blockieren das als Mixed Content.
5. Die Firewall erlaubt den Port. Firmennetze sperren 1883 und 8883 häufig für ausgehenden Verkehr.
6. Die Client ID ist nicht leer und eindeutig. Duplikate verursachen Disconnect-Schleifen.
7. Zugangsdaten stehen getrennt von der URL, es sei denn, die Bibliothek dokumentiert Zugangsdaten in der URL; in diesem Fall müssen Sonderzeichen URL-kodiert sein.
8. Der CA-Speicher des Clients vertraut dem Serverzertifikat. broker.connectmq.com nutzt ein Let's-Encrypt-Zertifikat, dem die üblichen System-Speicher vertrauen.

Die Broker-URL in der Konfiguration ablegen

Eine fest im Quellcode verankerte URL ist der schnellste Weg, Umgebungswechsel schmerzhaft zu machen. Halten Sie die vollständige URL samt Zugangsdaten und Client ID in der Konfiguration, damit derselbe Code in der Entwicklung auf den öffentlichen MQTT-Broker, im Staging auf einen privaten Broker und in der Produktion auf einen dedizierten Endpunkt zeigen kann.

Für die meisten Services genügt ein einfaches Schema aus Umgebungsvariablen:

export MQTT_URL="mqtts://broker.connectmq.com:8883"
export MQTT_USERNAME="YOUR_USERNAME"
export MQTT_PASSWORD="YOUR_PASSWORD"
export MQTT_CLIENT_ID="YOUR_CLIENT_ID"

Lesen Sie sie beim Start ein, zum Beispiel mit mqtt.connect(process.env.MQTT_URL, { clientId: process.env.MQTT_CLIENT_ID, username: process.env.MQTT_USERNAME, password: process.env.MQTT_PASSWORD }) in Node.js oder mit der Hilfsfunktion client_from_url von oben in Python. Ein paar Gewohnheiten machen das robust:

• Beim Start validieren. Lehnen Sie ein unbekanntes Schema oder eine WebSocket-URL ohne Pfad ab, bevor Sie eine Verbindung versuchen, und protokollieren Sie Schema, Host und Port (niemals das Passwort), damit Fehlkonfigurationen sofort auffallen.
• Geheimnisse getrennt von der URL halten. Legen Sie das Passwort in Ihrem Secret Manager und die URL in der normalen Konfiguration ab; so darf die URL gefahrlos in Logs und Dashboards erscheinen.
• Eine Variable pro Umgebung, nicht pro Transport. Braucht ein Browser-Build wss:// und ein Backend mqtts://, geben Sie jedem Deployment eine eigene Einstellung, statt die eine per String-Ersetzung aus der anderen abzuleiten.
• Das erwartete Format dokumentieren. Ein einzeiliger Kommentar wie scheme://host:port[/path] neben der Einstellung erspart dem nächsten Entwickler das Raten.

Öffentliche und private URLs

Der Hostname ist für den öffentlichen MQTT-Broker und für private Broker derselbe, was Beispiele einfach hält. Beim Öffentlichen MQTT-Broker, der für Tests und Prototypen gedacht ist, verbinden Sie sich anonym mit einer beliebigen eindeutigen Client ID und einem eindeutigen Topic-Präfix wie connectmq/demo/r4t9/...; dort ist alles für jeden lesbar. Ein privater ConnectMQ Broker nutzt dieselbe URL mit Ihrem generierten Benutzernamen, Passwort und Ihrer Client ID, und Ihr Datenverkehr bleibt in Ihrem eigenen isolierten Mandanten. Für das Gesamtbild der Hosting-Optionen lesen Sie den Leitfaden zum Cloud-MQTT-Broker und unseren Überblick, was ein MQTT Broker macht.

Ihre eigene Broker-URL bei ConnectMQ

Erstellen Sie unter app.connectmq.com ohne Kreditkarte einen kostenlosen Serverless Broker. Das Portal zeigt Ihre Endpunkte für alle vier Schemata zusammen mit generierten Zugangsdaten, und mit dem Browser-Client können Sie sofort eine wss://-Verbindung testen. ConnectMQ unterstützt MQTT 3.1.1 und 5.0 auf jedem Endpunkt.

Häufig gestellte Fragen

Was ist der Unterschied zwischen mqtt:// und mqtts://?

mqtt:// ist unverschlüsseltes TCP, meist auf Port 1883. mqtts:// verpackt dasselbe Protokoll in TLS, meist auf Port 8883, und verschlüsselt so Zugangsdaten und Payloads.

Warum schlägt meine wss://-Verbindung ohne Fehlermeldung fehl?

Die häufigste Ursache ist ein fehlender WebSocket-Pfad. Ergänzen Sie /mqtt in der URL und prüfen Sie, ob der Port der sichere WebSocket-Port ist, bei ConnectMQ 8084.

Kann ich Benutzername und Passwort in die MQTT-URL schreiben?

Manche Bibliotheken unterstützen scheme://user:pass@host:port, doch separate Optionen sind sicherer und verhindern, dass Geheimnisse in Logs landen.

Ist tcp:// dasselbe wie mqtt://?

Ja. Java- und Paho-Clients verwenden tcp:// und ssl://, die mqtt:// und mqtts:// entsprechen.