@capgo/capacitor-mqtt

Capacitor plugin for MQTT connectivity on Android and iOS using the Eclipse Paho MQTT library.

Why MQTT?

MQTT (Message Queuing Telemetry Transport) is a lightweight, publish-subscribe messaging protocol ideal for:

• IoT devices - Low bandwidth, minimal battery usage.
• Real-time messaging - Instant message delivery between clients
• Remote monitoring - Send/receive data from distributed devices
• Home automation - Connect smart devices seamlessly

This plugin provides a complete MQTT client implementation for Capacitor apps, supporting both Android and iOS.

This plugin is compatible with Capacitor 8 and above.

PR's are greatly appreciated.

Features

• Connect to MQTT brokers via TCP
• Subscribe to topics with QoS support
• Publish messages with QoS and retained flag options
• Listen for incoming messages
• Automatic reconnection support
• Connection loss detection
• Clean session management
• Keep-alive interval configuration

Installation

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-mqtt` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

npm install @capgo/capacitor-mqtt
npx cap sync

Android cleartext MQTT (tcp://)

Android blocks non-TLS MQTT (tcp://) by default. If your broker does not use TLS, add a network security config in your app:

<!-- android/app/src/main/res/xml/network_security_config.xml -->
<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <base-config cleartextTrafficPermitted="true" />
</network-security-config>

<!-- android/app/src/main/AndroidManifest.xml -->
<application
    android:usesCleartextTraffic="true"
    android:networkSecurityConfig="@xml/network_security_config">

Without this, connect() rejects with a broker connection error instead of silently failing.

Usage

Connect to MQTT Broker

import { MqttBridge } from '@capgo/capacitor-mqtt';

const connectionOptions = {
  serverURI: 'tcp://broker.hivemq.com',
  port: 1883,
  clientId: 'my-client-id',
  username: '',
  password: '',
  setCleanSession: true,
  connectionTimeout: 30,
  keepAliveInterval: 60,
  setAutomaticReconnect: true,
};

await MqttBridge.connect(connectionOptions);

Subscribe to Topic

const result = await MqttBridge.subscribe({
  topic: 'my/topic',
  qos: 0,
});

Publish Message

const result = await MqttBridge.publish({
  topic: 'my/topic',
  payload: 'Hello World',
  qos: 0,
  retained: false,
});

Listen for Messages

import { MqttBridge } from '@capgo/capacitor-mqtt';

MqttBridge.addListener('onMessageArrived', (result) => {
  console.log('Topic:', result.topic);
  console.log('Message:', result.message);
});

Disconnect

await MqttBridge.disconnect();

API

connect(options: { serverURI: string; port: number; clientId: string; username: string; password: string; setCleanSession: boolean; connectionTimeout: number; keepAliveInterval: number; setAutomaticReconnect: boolean; setLastWill?: { willTopic: string; willPayload: string; willQoS: number; setRetained: boolean; }; }) => Promise<any>

disconnect() => Promise<any>

subscribe(options: { topic: string; qos: number; }) => Promise<{ topic: string; qos: number; }>

publish(options: { topic: string; payload: string; qos: number; retained: boolean; }) => Promise<{ topic: string; payload: string; qos: number; retained: boolean; messageId: any; }>

addListener(eventName: 'onConnectionLost', listener: onConnectionLostListener) => Promise<PluginListenerHandle>

addListener(eventName: 'onConnectComplete', listener: onConnectCompleteListener) => Promise<PluginListenerHandle>

addListener(eventName: 'onMessageArrived', listener: onMessageArrivedListener) => Promise<PluginListenerHandle>

License

MPL-2.0