Skip to main content
MQTT Explorer provides a comprehensive connection setup interface that supports various MQTT broker configurations, from simple local connections to secure cloud deployments.

​
Quick Start

1

Open Connection Dialog

Launch MQTT Explorer and you’ll see the connection setup dialog. Click the ”+” button to create a new connection profile.
2

Configure Basic Settings

Enter your broker details:
  • Name: A friendly name for this connection (e.g., “Home Assistant”)
  • Host: Your MQTT broker hostname or IP address
  • Port: MQTT broker port (default: 1883 for non-encrypted, 8883 for TLS)
  • Protocol: Choose between mqtt:// (standard) or ws:// (WebSocket)
3

Connect

Click the “Connect” button to establish a connection to your broker.

​
Connection Parameters

​
Basic Configuration

​
name
string
required
A descriptive name for your connection profile. This helps you identify different brokers when managing multiple connections.Example: "Production MQTT Broker", "Home Assistant", "IoT Devices"
​
protocol
string
default:"mqtt"
The connection protocol to use:
  • mqtt: Standard MQTT protocol (TCP-based)
  • ws: WebSocket-based MQTT (required for browser mode)
Browser mode automatically uses WebSocket (ws:// or wss://) connections since browsers cannot make direct TCP connections.
​
host
string
required
The hostname or IP address of your MQTT broker.Examples:
  • localhost - Local broker
  • 192.168.1.100 - LAN broker
  • mqtt.example.com - Remote broker
  • mqtt.eclipseprojects.io - Public test broker
​
port
number
default:"1883"
The TCP port your MQTT broker listens on.Common ports:
  • 1883 - Standard MQTT (non-encrypted)
  • 8883 - MQTT over TLS/SSL
  • 8080 - WebSocket (ws://)
  • 8443 - WebSocket over TLS (wss://)
​
basePath
string
Required when using WebSocket protocol (ws://). Specifies the path component of the WebSocket URL.Default: ws when protocol is set to WebSocketExamples:
  • ws → connects to ws://broker.example.com:8080/ws
  • mqtt → connects to ws://broker.example.com:8080/mqtt
  • Empty for standard MQTT protocol

​
TLS/SSL Configuration

​
encryption
boolean
default:false
Enable TLS/SSL encryption for secure communication with your broker.When enabled:
  • Uses encrypted connection (port 8883 typically)
  • Protects credentials and message data in transit
  • Required for production deployments
​
certValidation
boolean
default:true
Validate the broker’s TLS certificate against trusted certificate authorities.
Disabling certificate validation makes your connection vulnerable to man-in-the-middle attacks. Only disable for testing with self-signed certificates, and use proper certificate management in production.
When disabled, you can connect to brokers with:
  • Self-signed certificates
  • Expired certificates
  • Certificate hostname mismatches

​
Connection Profiles

MQTT Explorer allows you to save multiple connection profiles for quick access to different brokers.

​
Creating a Profile

  1. Click the ”+” button in the connection dialog
  2. Enter your broker details
  3. Click Save to persist the connection profile
  4. The profile is stored locally and will be available in future sessions

​
Managing Profiles

Switch Profiles

Select a different profile from the list on the left side of the connection dialog. Each profile retains its own settings.

Edit Profile

Select a profile and modify any settings. Click Save to update the profile with your changes.

Delete Profile

Select a profile and click the Delete button. You’ll be prompted to confirm the deletion.

Duplicate Profile

Create a new profile based on an existing one by copying the connection details and modifying them as needed.

​
Default Profiles

MQTT Explorer includes pre-configured profiles for public test brokers:
A public MQTT broker provided by the Eclipse Foundation.
  • Host: mqtt.eclipseprojects.io
  • Port: 1883
  • Protocol: mqtt
  • Authentication: None required
  • Use case: Testing and learning MQTT
This is a public broker. Never send sensitive data or use it for production applications.
A public test MQTT broker by Eclipse Mosquitto.
  • Host: test.mosquitto.org
  • Port: 1883
  • Protocol: mqtt
  • Authentication: None required
  • Use case: Testing and learning MQTT
This broker supports multiple ports for testing different configurations (TLS, WebSockets, etc.).

​
Auto-Connect (Server Mode)

When running MQTT Explorer in browser/server mode, you can configure automatic connection using environment variables. 
# Basic auto-connect
export MQTT_AUTO_CONNECT_HOST=mqtt.example.com
export MQTT_AUTO_CONNECT_PORT=1883

# With authentication
export MQTT_AUTO_CONNECT_USERNAME=myuser
export MQTT_AUTO_CONNECT_PASSWORD=mypassword

# With custom protocol and client ID
export MQTT_AUTO_CONNECT_PROTOCOL=mqtt
export MQTT_AUTO_CONNECT_CLIENT_ID=mqtt-explorer-server

# Start server
node dist/src/server.js
When MQTT_AUTO_CONNECT_HOST is set, MQTT Explorer will automatically connect to the specified broker on startup.
See the Environment Variables guide for complete configuration options.

​
Client ID

​
clientId
string
A unique identifier for this MQTT client connection.Default: Auto-generated as mqtt-explorer-[random]The client ID is used by the broker to:
  • Identify your connection in broker logs
  • Manage persistent sessions
  • Prevent duplicate connections
If two clients connect with the same client ID, the broker will disconnect the first client. Use unique client IDs for each connection.

​
When to Customize Client ID

  • Persistent sessions: Use a consistent client ID to maintain subscriptions across reconnections
  • Debugging: Use descriptive client IDs to identify connections in broker logs
  • Multiple instances: Ensure each instance has a unique client ID to prevent conflicts

​
Keyboard Shortcuts

The connection dialog supports several keyboard shortcuts for quick navigation:
  • Enter: Connect to the selected profile
  • Escape: Disconnect from the current connection
  • Ctrl+S / Cmd+S: Save the current profile

​
Connection States

MQTT Explorer displays the current connection state:
1

Disconnected

Not connected to any broker. The Connect button is enabled.
2

Connecting

Connection attempt in progress. You can click the button again to cancel.
3

Connected

Successfully connected to the broker. The main interface shows the topic tree.
4

Error

Connection failed. Check your settings and broker availability.

​
Troubleshooting

Causes:
  • Broker is not running
  • Firewall blocking the connection
  • Incorrect host or port
Solutions:
  • Verify the broker is running: mosquitto -v
  • Check firewall rules allow the port
  • Confirm host and port are correct
  • Try connecting from command line: mosquitto_sub -h host -p port -t #
Causes:
  • Broker is unreachable
  • Network connectivity issues
  • Broker is overwhelmed
Solutions:
  • Verify network connectivity: ping broker.example.com
  • Check if broker is responding: telnet broker.example.com 1883
  • Try a different network or VPN connection
Causes:
  • Incorrect username or password
  • Broker requires authentication but none provided
  • User doesn’t have connection permissions
Solutions:
  • Verify credentials are correct
  • Check broker logs for authentication errors
  • Ensure user has ACL permissions to connect
  • See Authentication guide for details
Causes:
  • Certificate validation failure
  • Self-signed certificate without proper configuration
  • TLS version mismatch
Solutions:
  • For self-signed certificates, disable certificate validation (testing only)
  • Install proper CA certificates
  • Check TLS version compatibility
  • See TLS/SSL guide for detailed configuration
Causes:
  • Incorrect basePath
  • Broker doesn’t support WebSocket
  • CORS issues in browser mode
Solutions:
  • Verify broker has WebSocket listener configured
  • Check basePath matches broker configuration
  • Ensure broker allows CORS for your domain (browser mode)
  • Try standard MQTT protocol instead

​
Best Practices

Use Descriptive Names

Name your connection profiles clearly to distinguish between different brokers and environments (e.g., “Production”, “Staging”, “Local Dev”).

Enable TLS in Production

Always use TLS/SSL encryption for production deployments to protect credentials and message data.

Test with Public Brokers

Use public test brokers to learn MQTT and verify your setup before connecting to production brokers.

Unique Client IDs

Use unique client IDs for each connection to prevent conflicts and make debugging easier.

​
Next Steps

Authentication

Learn how to configure username/password authentication and access control.

TLS/SSL Configuration

Set up encrypted connections with certificates for secure communication.

Advanced Settings

Configure custom subscriptions, QoS levels, and advanced MQTT options.

Environment Variables

Configure MQTT Explorer using environment variables for server deployments.

Build docs developers (and LLMs) love

Get started for freeTalk to us