macOS CLI Terminal companion and local MCP server

EasyMQTT CLI

Use EasyMQTT from Terminal. Publish, subscribe, test broker connections, inspect saved brokers and favorites, query recent history, and run a local MCP server for agent workflows.

Install with Homebrew GitHub releases

Standalone macOS tool MCP stdio server EasyMQTT app data aware

$ easymqtt test --broker Home
DNS      ok   broker.example.com resolved
TCP      ok   connected to 1883
TLS      skip plaintext broker
MQTT     ok   CONNACK accepted

$ easymqtt publish --broker Home \
  --topic sensors/office \
  --message "hello"
published sensors/office qos=0 retain=false

What it does

A practical macOS tool for MQTT work.

Publish and subscribe

Publish MQTT messages from Terminal and subscribe to one or more topics, including wildcard topics for live inspection.

Diagnose broker access

Test broker connectivity with DNS, TCP, TLS, and MQTT diagnostics before debugging the rest of your stack.

Use saved EasyMQTT data

List, add, inspect, and remove saved brokers. List and create publish or subscription favorites from the command line.

Query history

Inspect recent MQTT history and output human-readable tables or JSON where supported.

Run an MCP server

Start a local stdio MCP server that exposes EasyMQTT brokers, favorites, history, and live MQTT operations to compatible local agents.

Install

Install with Homebrew.

The CLI runs on macOS and ships as a standalone notarized tool named easymqtt.

Homebrew

brew tap LucaKaufmann/tap
brew install easymqtt

Verify

which easymqtt
easymqtt --help
easymqtt mcp --help

You can also install the notarized universal macOS package from GitHub releases.

sudo installer -pkg easymqtt-macos-universal.pkg -target /

Commands

Copy-friendly examples.

Use saved brokers when they exist, or pass broker details manually for one-off work.

Brokers

easymqtt brokers list
easymqtt brokers list --json

easymqtt brokers add \
  --name Home \
  --host broker.example.com \
  --port 1883

Diagnostics

easymqtt test --broker Home

Publish

easymqtt publish \
  --broker Home \
  --topic sensors/office \
  --message "hello"

easymqtt subscribe \
  --broker Home \
  --topic "sensors/#" \
  --duration 10

Favorites

easymqtt favorites list

History

easymqtt history --limit 20
easymqtt history \
  --topic sensors \
  --since 1h \
  --json

EasyMQTT app data

How the CLI works with the app.

If EasyMQTT is installed on the same Mac, the CLI can use the app's shared database automatically. Terminal commands and MCP tools can reuse saved brokers, publish favorites, subscription favorites, and recent history from the EasyMQTT Mac app.

Default shared database

Users usually do not need to configure this manually.

~/Library/Group Containers/group.com.mqtthings.EasyMQTT/EasyMQTT-v2.sqlite

Explicit database path

If auto-detection does not work, set EASYMQTT_DB_PATH.

EASYMQTT_DB_PATH="$HOME/Library/Group Containers/group.com.mqtthings.EasyMQTT/EasyMQTT-v2.sqlite" easymqtt brokers list --json

Mac companion nuance

The CLI cannot directly read data from an iPhone-only install. For shared app data, install or use EasyMQTT on the same Mac, open it once, and save brokers or favorites there.

Manual broker details

You can still use the CLI without saved app data by passing broker details directly.

easymqtt publish \
  --host broker.example.com \
  --port 1883 \
  --topic sensors/office \
  --message "hello"

MCP server

Local MQTT tools for compatible agents.

easymqtt mcp starts a local stdio MCP server for agent workflows on your Mac.

MCP tools

mqtt_connect
mqtt_disconnect
mqtt_publish
mqtt_subscribe
mqtt_unsubscribe
mqtt_test_connection
mqtt_list_topics
easymqtt_list_brokers
easymqtt_list_favorites
easymqtt_recent_history
easymqtt_save_broker
easymqtt_save_favorite
easymqtt_delete_broker

MCP resources

easymqtt://brokers
easymqtt://favorites
easymqtt://history/recent
easymqtt://history/<topic>?since=...&limit=...

MCP prompts

mqtt_setup_guide
mqtt_debug
mqtt_monitor

Claude Code

claude mcp add --transport stdio --scope project easymqtt -- easymqtt mcp

If the binary is not on PATH, use the full path:

claude mcp add --transport stdio --scope project easymqtt -- /opt/homebrew/bin/easymqtt mcp

Claude Desktop-style JSON

{
  "mcpServers": {
    "easymqtt": {
      "type": "stdio",
      "command": "/opt/homebrew/bin/easymqtt",
      "args": ["mcp"],
      "env": {
        "EASYMQTT_DB_PATH": "/Users/you/Library/Group Containers/group.com.mqtthings.EasyMQTT/EasyMQTT-v2.sqlite"
      }
    }
  }
}

Troubleshooting

Common fixes.

command not found+

Run which easymqtt, or use the full Homebrew path such as /opt/homebrew/bin/easymqtt.

Empty brokers, favorites, or history+

Open EasyMQTT on the Mac and save data there, or set EASYMQTT_DB_PATH to the shared database path.

MCP tools do not appear+

Restart the MCP client or verify the server with that client's MCP status command.

Connection failures+

Run easymqtt test --broker <name> or pass manual broker details with --host, --port, --tls, --username, and --password.