How to Get MQTT Notifications on Mac

Short answer

Point a subscriber at your broker and let macOS show the message.

MQTT is a publish/subscribe protocol: your scripts, sensors and automations publish to a broker, and something on your Mac has to stay subscribed to turn those messages into notifications. For a native inbox, install NTBX, add the broker URL and topic filter, allow macOS notifications, and leave it running in the menu bar. If you would rather keep everything in a terminal, mosquitto_sub plus a notification command works too — the comparison below covers the trade-offs.

Jump to the broker setup and publish test →

At a glance

Four ways to receive MQTT messages on a Mac.

The first two rows are the common choices. The difference that matters later is whether you want an event log — messages with topics, timestamps and click links you can search — or a live readout of state.

Method 1

Use a native Mac client.

A native client keeps the subscription, the session and the notification permission in one place, so a broker restart or a sleeping Mac does not silently end your alerts. Look for a client that speaks MQTT 3.1.1 over both TCP and WebSocket, stores broker passwords in the Keychain, and shows messages as normal macOS alerts rather than in its own window.

Native Mac quick start

Connect NTBX to a broker.

1. Install NTBX and allow notifications. macOS 14 or later from the Mac App Store. Grant notification permission on first launch; enable launch at login if the Mac should always be listening.
2. Add the broker URL. Use mqtt://host:1883 for plaintext TCP, mqtts://host:8883 for TLS, or a WebSocket endpoint such as wss://host:443/mqtt. NTBX defaults WebSocket URLs to the /mqtt path when you leave it out.
3. Choose a topic filter. alerts/# follows a whole tree, alerts/+/disk one level. Pick QoS 1 if a message must arrive, QoS 0 for high-volume topics where the occasional loss is fine.
4. Add credentials if the broker needs them. Username and password are stored per subscription; the password goes into macOS Keychain. A custom Client ID is optional and limited to 1–23 ASCII alphanumeric characters.
5. Test, then save. Test Connection checks reachability, TLS and authentication before you commit, and the app warns when a broker URL is plaintext.

Two details surprise people coming from a debugging client. Retained messages are ignored on purpose: broker state is not a new event, and re-delivering it on every reconnect would produce phantom notifications. And QoS 2 is out of scope — subscriptions use QoS 0 or 1, which is what notification workloads need.

MQTT specification reference →

Verify the path

Publish a test message.

Send one message and watch it arrive. The command below needs mosquitto-clients from Homebrew (brew install mosquitto) or any other MQTT client:

mosquitto_pub \
  -h broker.example.com -p 8883 \
  -t alerts/disk \
  -m 'Disk almost full on mac-studio' \
  -q 1

For a broker that requires authentication add --username and --pw; for a broker with a private certificate authority add --cafile /path/to/ca.crt. To confirm the broker received your message independently of NTBX, subscribe in a second terminal:

mosquitto_sub \
  -h broker.example.com -p 8883 \
  -t 'alerts/#' -v -q 1

WebSocket brokers are reached with a URL rather than a host and port. Point any client at wss://broker.example.com/mqtt; NTBX takes the same URL. If port 1883 is closed on your network but HTTPS works, WebSocket is usually the way through.

Where the messages come from

Three brokers you can use today.

• A local broker for testing. Run Mosquitto in Docker or through Homebrew and subscribe to mqtt://localhost:1883. Nothing leaves the Mac, and it is the fastest way to check that filters and QoS behave as you expect.
• Home Assistant's built-in broker. If Home Assistant already runs the Mosquitto add-on, point NTBX at that broker and subscribe to the topics your automations publish to — Zigbee2MQTT device topics on the same broker work exactly the same way. An automation can push an alert with the MQTT integration's mqtt.publish action; NTBX only reads, so it never interferes with your devices.
• A public test broker. test.mosquitto.org offers an unencrypted listener on 1883, TLS on 8883, and WebSocket listeners on 8080 and 8081 for quick experiments. Public brokers are shared, so treat every topic as public and never send credentials or private data.

Whichever you pick, use TLS outside your own network: mqtts:// or wss:// encrypts both the payload and, with it, the username and password. NTBX validates certificates against the macOS trust store, so a self-signed broker certificate will fail unless it is trusted by the system.

test.mosquitto.org listeners → · Home Assistant MQTT integration →

Getting the filter right

Topic filters, QoS and payloads.

• + matches one level, # matches the rest. home/+/temperature catches every room; home/# catches everything below home. A # that is not the last level is invalid, and so is a filter that contains a wildcard inside a level.
• QoS 1 for alerts, QoS 0 for chatter. QoS 1 asks the broker to acknowledge delivery, which suits a message you must not miss. QoS 0 avoids the round trip and is fine for frequent sensor readings.
• Sessions resume, with one deliberate exception. NTBX keeps a persistent session and cleans it on the broker when the broker, filter, QoS, username or Client ID changes, so a config change does not leave a stale subscription delivering duplicates.
• Payloads are text by default. UTF-8 payloads become the notification body; non-UTF-8 payloads are either skipped or shown as Base64, per subscription. Publishes larger than 256 KiB are dropped rather than truncated.

When nothing arrives

Fix the five usual failures.

Recommendation

Pick by what you need to see.

Use mosquitto_sub to answer "is this topic alive right now?" — it is the fastest tool for a one-off check. Use a debugging client when you need to inspect payload shapes, retained values or publish behaviour. Use a native Mac client when the question is "which messages should interrupt me today, and where do I find them tomorrow?" That is the case this guide is about, and the one NTBX is built for.