Quick Start

Get Started in Minutes

This guide will walk you through connecting to an MQTT broker and exploring your first messages.

Launch MQTT Explorer

Open the application or navigate to your browser deployment.

Create a connection

Click + New Connection or select an existing connection from the list.

Configure and connect

Enter your broker details and click Connect.

Explore topics

Browse the topic tree, inspect messages, and publish your own.

Quick Connection Example

Try connecting to a public test broker to explore MQTT Explorer’s features:

Test Broker: Mosquitto

The Eclipse Mosquitto project provides a free public test broker:

Name: Test Mosquitto
Host: test.mosquitto.org
Port: 1883
Protocol: mqtt
Username: (none)
Password: (none)
Encryption: Disabled

Subscriptions:
  - Topic: #
    QoS: 0
  - Topic: $SYS/#
    QoS: 0

Default SubscriptionsMQTT Explorer automatically subscribes to:

# - All topics (wildcard)
$SYS/# - Broker system information

You can modify these in Advanced Settings.

Connection Setup

Basic Connection

Open Connection Dialog

Click + Create Connection in the sidebar

Enter Basic Details

name

string

required

A friendly name for this connection (e.g., “Production Broker”, “Home Assistant”)

host

string

required

Broker hostname or IP address (e.g., test.mosquitto.org, 192.168.1.100)

port

number

default:"1883"

MQTT port (default: 1883 for plain, 8883 for TLS, 80/443 for WebSocket)

protocol

string

default:"mqtt"

Connection protocol:

mqtt - Standard MQTT over TCP
ws - MQTT over WebSocket

Configure Authentication (Optional)

If your broker requires authentication:

username

string

MQTT username

password

string

MQTT password

Many public test brokers don’t require authentication. For production brokers, always use authentication and encryption.

Connect

Click Connect to establish the connection.Once connected, you’ll see:

Topic tree in the left sidebar
Connection status indicator (green)
Real-time message count

Working With Topics

Viewing Topics

Once connected, topics appear in a hierarchical tree structure:

📁 home
  📁 livingroom
    📄 temperature: 22.5
    📄 humidity: 45
  📁 bedroom
    📄 temperature: 20.1
    📄 humidity: 50
📁 $SYS
  📁 broker
    📄 version: mosquitto 2.0.15
    📄 uptime: 3600 seconds

Topic Structure:

📁 Folder icon = Topic level (branch)
📄 Document icon = Topic with message (leaf)
Bold = Recently updated topic
Color coding = Message age (newer = brighter)

Inspecting Messages

Click any topic to view:

Value
History
Stats
Chart

The current message payload:

Raw: Plain text view
JSON: Formatted JSON with syntax highlighting
Hex: Hexadecimal view for binary data

Publishing Messages

Publish Your First Message

Select Topic

Click any topic in the tree, or manually enter a topic in the Publish panel.

Enter Message Details

In the Publish panel (usually at the bottom):

topic

string

required

Topic to publish to (e.g., home/livingroom/light/command)

payload

string

required

Message payload (text, JSON, or binary)

qos

number

default:"0"

Quality of Service level:

0 - At most once (fire and forget)
1 - At least once (acknowledged)
2 - Exactly once (assured delivery)

retain

boolean

default:"false"

Retain flag - if enabled, broker stores message and sends to new subscribers

Publish

Click Publish to send the message.If subscribed to the topic, you’ll see your message appear immediately in the topic tree.

Example: Publish JSON

{
  "device": "sensor-01",
  "temperature": 22.5,
  "humidity": 45,
  "timestamp": "2026-03-05T12:00:00Z"
}

Publish to topic: home/livingroom/sensor

MQTT Explorer automatically validates and formats JSON payloads. Invalid JSON is highlighted with error details.

Advanced Settings

Client ID

MQTT Explorer generates a unique client ID automatically:

mqtt-explorer-a1b2c3d4

You can customize this in Advanced Connection Settings.

Unique Client IDsEach MQTT client must have a unique client ID. If two clients connect with the same ID, the broker will disconnect the first client.

Custom Subscriptions

Modify the default subscriptions in Advanced Settings: Examples:

# Subscribe to specific device
sensor/bedroom/+

# Multiple levels wildcard
home/#

# Specific topics only
home/livingroom/temperature
home/bedroom/humidity

# Exclude system topics
# (remove $SYS/# subscription)

Wildcard Characters:

+ - Single level wildcard (e.g., home/+/temperature)
# - Multi-level wildcard (e.g., home/#)

WebSocket Connections

For brokers that support MQTT over WebSocket:

Protocol: ws
Port: 80 (or 443 for wss)
Basepath: /mqtt (if required)

Common WebSocket Paths:

HiveMQ: /mqtt
Mosquitto: / (default)
AWS IoT: /mqtt
Azure IoT Hub: /$iothub/websocket

WebSocket connections are useful when:

MQTT port (1883) is blocked by firewall
Connecting from browser environments
Using cloud MQTT services

TLS/SSL Encryption

For secure connections with encryption:

Enable Encryption

Check Enable TLS/SSL in connection settings

Update Port

Change port to 8883 (standard MQTT/TLS port)

Certificate Validation

Enable certificate validation for production brokers.Disable only for:

Testing with self-signed certificates
Development environments

Security Risk: Disabling certificate validation removes protection against man-in-the-middle attacks. Use only for testing.

Upload Certificates (Optional)

For self-signed certificates or client authentication:

CA Certificate: Broker’s Certificate Authority
Client Certificate: Your client certificate
Client Key: Private key for client certificate

Desktop App
Browser/Docker

Click Select File to browse for certificate files from your filesystem.

Real-World Examples

Home Assistant

Connect to Home Assistant’s built-in MQTT broker:

Host: homeassistant.local
Port: 1883
Username: mqtt_user
Password: your_password
Protocol: mqtt

Subscriptions:
  - homeassistant/#
  - $SYS/#

AWS IoT Core

Host: your-endpoint.iot.us-east-1.amazonaws.com
Port: 8883
Protocol: mqtt
Encryption: Enabled
Cert Validation: Enabled

Certificates:
  - CA: AmazonRootCA1.pem
  - Client Cert: device-certificate.pem.crt
  - Client Key: private.pem.key

HiveMQ Cloud

Host: your-cluster.s1.eu.hivemq.cloud
Port: 8883
Username: your_username
Password: your_password
Protocol: mqtt
Encryption: Enabled

Local Mosquitto (Docker)

Host: localhost (or 172.17.0.1 from another container)
Port: 1883
Username: mosquitto
Password: mosquitto
Protocol: mqtt

Next Steps

Topic Visualization

Learn about the hierarchical topic tree and filtering

Message Publishing

Master message publishing with QoS and retain flags

TLS/SSL Setup

Configure secure encrypted connections

Protocol Decoders

Decode Protobuf and Sparkplug B messages

Troubleshooting

Connection Refused

Possible causes:

Broker is not running
Wrong host or port
Firewall blocking connection
Network connectivity issues

Solutions:

Verify broker is running: netstat -an | grep 1883
Test connectivity: telnet broker-host 1883
Check firewall rules
Try a public test broker first

Authentication Failed

Solutions:

Verify username and password
Check broker access control list (ACL)
Confirm authentication is required
Check broker logs for details

No Topics Appearing

Possible causes:

No messages published yet
Subscription filters too restrictive
ACL restricts topic access

Solutions:

Publish a test message
Check subscription patterns
Verify ACL permissions on broker
Check broker logs

TLS/SSL Connection Failed

Solutions:

Verify port is 8883 (not 1883)
Check certificate validation setting
Upload CA certificate for self-signed certs
Verify broker TLS configuration
Check certificate expiration dates

Need More Help?

Report issues or ask questions on GitHub

Get Started

Deployment

Features

Guides

Advanced

Get Started in Minutes

Quick Connection Example

Test Broker: Mosquitto

Connection Setup

Basic Connection

Working With Topics

Viewing Topics

Inspecting Messages

Publishing Messages

Publish Your First Message

Example: Publish JSON

Advanced Settings

Client ID

Custom Subscriptions

WebSocket Connections

TLS/SSL Encryption

Real-World Examples

Home Assistant

AWS IoT Core

HiveMQ Cloud

Local Mosquitto (Docker)

Next Steps

Topic Visualization

Message Publishing

TLS/SSL Setup

Protocol Decoders

Troubleshooting

Need More Help?

Build docs developers (and LLMs) love

Get Started

Deployment

Features

Guides

Advanced

​Get Started in Minutes

​Quick Connection Example

​Test Broker: Mosquitto

​Connection Setup

​Basic Connection

​Working With Topics

​Viewing Topics

​Inspecting Messages

​Publishing Messages

​Publish Your First Message

​Example: Publish JSON

​Advanced Settings

​Client ID

​Custom Subscriptions

​WebSocket Connections

​TLS/SSL Encryption

​Real-World Examples

​Home Assistant

​AWS IoT Core

​HiveMQ Cloud

​Local Mosquitto (Docker)

​Next Steps

Topic Visualization

Message Publishing

TLS/SSL Setup

Protocol Decoders

​Troubleshooting

Need More Help?

Build docs developers (and LLMs) love

Get Started in Minutes

Quick Connection Example

Test Broker: Mosquitto

Connection Setup

Basic Connection

Working With Topics

Viewing Topics

Inspecting Messages

Publishing Messages

Publish Your First Message

Example: Publish JSON

Advanced Settings

Client ID

Custom Subscriptions

WebSocket Connections

TLS/SSL Encryption

Real-World Examples

Home Assistant

AWS IoT Core

HiveMQ Cloud

Local Mosquitto (Docker)

Next Steps

Troubleshooting