@capgo/capacitor-mqtt

Connect your Capacitor app to an MQTT broker on iOS and Android for real-time IoT messaging: publish, subscribe and react to messages as they arrive.

🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use @capgo/capacitor-mqtt in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-mqtt to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

Key features

• Connect: connect() with server URI, port, client ID, credentials, timeouts and automatic reconnect.
• Publish: publish() sends a payload to a topic with QoS and retain options.
• Subscribe: subscribe() to topics with a QoS level.
• Events: onMessageArrived, onConnectComplete and onConnectionLost listeners.
• Native clients: CocoaMQTT on iOS and Eclipse Paho on Android.
• Platforms: iOS and Android. Not available on web.

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(...)
• disconnect()
• subscribe(...)
• publish(...)
• addListener('onConnectionLost', ...)
• addListener('onConnectComplete', ...)
• addListener('onMessageArrived', ...)
• Interfaces
• Type Aliases

connect(...)

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>

Returns: Promise<any>

disconnect()

disconnect() => Promise<any>

Returns: Promise<any>

subscribe(...)

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

Returns: Promise<{ topic: string; qos: number; }>

publish(...)

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

Returns: Promise<{ topic: string; payload: string; qos: number; retained: boolean; messageId: any; }>

addListener('onConnectionLost', ...)

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

Returns: Promise<PluginListenerHandle>

addListener('onConnectComplete', ...)

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

Returns: Promise<PluginListenerHandle>

addListener('onMessageArrived', ...)

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

Returns: Promise<PluginListenerHandle>

Interfaces

PluginListenerHandle

Type Aliases

onConnectionLostListener

(x: { connectionStatus: string; reasonCode: number; message: string; }): void

onConnectCompleteListener

(x: { reconnected: boolean; serverURI: string; }): void

onMessageArrivedListener

(x: { topic: string; message: string; }): void

License

MPL-2.0