MQTT Explorer: How to Inspect and Debug a Broker

MQTT Explorer is a free desktop client that subscribes to a broker and shows everything it receives as a live, collapsible topic tree. It is the fastest way to answer "what is actually on this broker?": which topics exist, which ones hold retained messages, what changed in the last payload and how a value evolves over time. This guide covers installing it, connecting securely, and the features that matter when you debug.

Install MQTT Explorer

MQTT Explorer by Thomas Nordquist runs on Windows, macOS and Linux. Download it from mqtt-explorer.com or the project's GitHub releases, or use a package manager:

# macOS (Homebrew)
brew install --cask mqtt-explorer

# Linux (Snap)
sudo snap install mqtt-explorer

# Windows (winget)
winget install thomasnordquist.MQTT-Explorer

On Linux the AppImage also works without installation. Package names can change between releases, so if one of these fails, grab the build from the releases page.

Connect to a broker

The connection dialog opens on start. Fill in:

Prefer TLS whenever credentials are involved — on plain 1883 the password travels in clear text. Leave Validate certificate on; turning it off hides real problems such as a hostname mismatch. For a broker with a private CA, add the CA file under Advanced → Certificates instead.

In Advanced you can also set the MQTT Client ID. Give it a recognisable name like explorer-yourname; if you reuse the ID of a running device, the broker disconnects one of them and you will chase a phantom bug ("session taken over"). The client ID generator helps if you need a unique one.

Generate something to look at

To follow along, publish a few messages to your test prefix — retained status messages and a changing telemetry value:

H=broker.connectmq.com
P=testmqtt/explorer

mosquitto_pub -h $H -t "$P/device-1/status" -m online -r
mosquitto_pub -h $H -t "$P/device-2/status" -m offline -r
mosquitto_pub -h $H -t "$P/config" -m '{"interval":5,"unit":"C"}' -r

for i in $(seq 1 30); do
  T=$(awk -v s=$RANDOM 'BEGIN{srand(s); printf "%.1f", 20+rand()*3}')
  mosquitto_pub -h $H -t "$P/device-1/temperature" -m "{\"temp\":$T,\"seq\":$i}"
  sleep 2
done

You can do the same from the browser with the online MQTT client if you don't have the mosquitto tools installed.

Read the topic tree

The left pane builds the hierarchy from topic levels: testmqtt → explorer → device-1 → temperature. Each node shows how many sub-topics and messages it contains, and nodes briefly highlight when a new message arrives, so busy branches are easy to spot.

Use the tree to check your topic design:

• Typos and case differences stand out immediately — Device-1 and device-1 are separate branches, because MQTT topics are case-sensitive.
• Leading or trailing slashes create an empty level (/testmqtt/... has a blank root node).
• Unexpected depth — payload data accidentally encoded into the topic (.../temperature/21.5) shows up as hundreds of sibling nodes.

The search box at the top filters the tree by topic name. To check how a wildcard subscription would behave against those topics, use the topic matcher. More on structure in MQTT topics and wildcards.

Inspect values, history and diffs

Click a topic and the sidebar shows its latest value, formatted as JSON when the payload parses, along with QoS, retained flag and receive time. Below it is the history of recent messages on that topic.

When a payload changes, MQTT Explorer can show a diff against the previous message, so a single changed field in a large JSON document is obvious. This is ideal for questions like "which field does the firmware update on every report?" or "did the config change after the deploy?".

For numeric values — either a plain number or a numeric field inside JSON — use the chart option in the history to plot the value over time. A sawtooth pattern, a stuck sensor or a value that resets to zero after each reconnect is much easier to see on a chart than in a message list.

Find and delete retained messages

Retained messages are the most common source of "ghost" data: a device that has been offline for months still appears online because its last retained status is on the broker. In MQTT Explorer, retained messages are marked in the value panel, so you can walk the tree and see which topics hold one.

To remove one, select the topic and click the delete icon in the Topic section. The client publishes an empty retained message to that topic, which is the standard way to clear it. For a whole branch, use the recursive delete. Two caveats:

• Your user needs publish permission on those topics. If the ACL denies it, the deletion silently does nothing on many brokers — see ACL denied silently.
• A device that republishes its retained state on reconnect will bring the message back. Fix the source, not just the broker.

If a retained message keeps coming back anyway, retained message won't clear walks through the remaining causes.

Publish test messages

The Publish section in the sidebar sends a message to any topic, with a payload editor (raw, JSON or XML), QoS and retain options. Clicking a topic in the tree prefills its name, which makes it quick to replay or tweak an existing message — for example sending a command to testmqtt/explorer/device-1/set and watching the device's status topic change.

Watch $SYS for broker health

Many brokers publish statistics under $SYS/ — connected clients, message rates, uptime. Keep the $SYS/# subscription if your broker supports it and plot $SYS/broker/clients/connected or the load counters while you test. Which topics exist depends on the broker; MQTT $SYS topics lists the common ones. Managed services may restrict or omit $SYS.

Common problems

MQTT Explorer or another client?

MQTT Explorer is unmatched for browsing: topic trees, retained messages, diffs and quick charts. It is less suited to testing MQTT 5 features or juggling many parallel connections — MQTTX is stronger there, and the desktop MQTT clients comparison covers the rest. For a zero-install check from any machine, use the browser client.

Publish test data from your browser

Keep MQTT Explorer open while you develop: point it at a narrow prefix on a TLS connection, let the tree show you what your devices really publish, and use the diff, chart and retained views to turn "something is wrong" into a specific topic and field. It complements, rather than replaces, scripted tests that check the same things automatically.

Frequently asked questions