Matterbridge mqtt plugin

---

Features

The matterbridge-mqtt plugin bridges any MQTT-capable device into the Matter ecosystem through Matterbridge, without requiring device-specific firmware or custom integrations.

• Zero-code device onboarding — send a single retained config message and Matterbridge automatically creates and registers the corresponding Matter endpoint.
• Broad device-type support — lights (on/off, dimmable, colour-temperature, extended colour), plugs and outlets, mounted switches, sensors (contact, temperature, humidity, pressure, flow, light, occupancy, smoke/CO, air quality, rain, soil, water freeze/leak), pump, water valve, power source, and electrical sensor.
• Live state sync — retained state messages drive cluster attribute updates so controllers always see the current device state, even after a restart.
• Selective attribute subscription — a retained subscribe message lets each device declare exactly which cluster attributes it wants pushed back to its write topic.
• Matter state forwarding — every Matter attribute change (e.g. onOff, currentLevel) is published back to the device's write topic as a structured JSON payload.
• Flexible MQTT connectivity — configurable broker host, port, protocol version (3/4/5), credentials, client ID, and full TLS support (CA certificate, client certificate/key, rejectUnauthorized).
• Topic-based multi-device management — a single broker connection and a single base topic handle an arbitrary number of devices; each device is identified by its deviceId path segment.
• Frontend — a plugin frontend showing the created devices and all MQTT data.

---

How it works

Configuration

The plugin is configured through the Matterbridge frontend. The settings are stored in ~/.matterbridge/matterbridge-mqtt.config.json.

Parameter	Default	Description
host	mqtt://localhost	Broker URL. Use mqtt:// for plain TCP, mqtts:// for TLS, ws:// for WebSocket, wss:// for secure WebSocket.
port	1883	Broker port. Common values: 1883 (plain), 8883 (TLS), 9001 (WebSocket).
protocolVersion	5	MQTT protocol version: 3, 4 (MQTT 3.1.1), or 5.
clientId	(auto)	Client identifier sent to the broker. Leave empty to let the library generate one.
username	(empty)	Username for broker authentication. Leave empty if the broker does not require credentials.
password	(empty)	Password for broker authentication.
ca	(empty)	Path to the CA certificate file for TLS broker verification.
cert	(empty)	Path to the client certificate file for mutual TLS authentication.
key	(empty)	Path to the client private key file for mutual TLS authentication.
rejectUnauthorized	true	Reject brokers with self-signed or untrusted TLS certificates. Set to false for self-signed brokers.
topic	matterbridge	Base topic prefix used for all device topics.

Minimal configuration example

{
  "host": "mqtt://192.168.1.10",
  "port": 1883,
  "protocolVersion": 5,
  "topic": "matterbridge"
}

TLS configuration example

{
  "host": "mqtts://broker.example.com",
  "port": 8883,
  "protocolVersion": 5,
  "ca": "/path/to/ca.crt",
  "cert": "/path/to/client.crt",
  "key": "/path/to/client.key",
  "rejectUnauthorized": true,
  "topic": "matterbridge"
}

Topic structure

All topics follow the pattern <topic>/<deviceId>/<subTopic>/root, where <topic> is the configured base topic (default: matterbridge) and <deviceId> is a stable identifier you choose for each device.

Publish

Each device shall publish retained config, state and subscribe messages:

Device types, clusters and attributes all use their Matter names without spaces: device types (e.g. PowerSource, DimmableLight), clusters (e.g. PowerSource, OnOff, LevelControl) and attributes (e.g. onOff, currentLevel).

config

• matterbridge/deviceid/config/root

Publish here only the fixed and optional attributes.

const config = {
  deviceTypes: ['DimmableLight'],
  clusters: { BridgedDeviceBasicInformation: { nodeLabel: 'Light 1', serialNumber: 'xxx-yyy-xxx' }, LevelControl: { onLevel: 128 } },
};
publish('matterbridge/light1/config/root', JSON.stringify(config), { retain: true, qos: 2 });

state

• matterbridge/deviceid/state/root

Publish here only the current attribute values.

const state = { OnOff: { onOff: false }, LevelControl: { currentLevel: 254 } };
publish('matterbridge/deviceid/state/root', JSON.stringify(state), { retain: true, qos: 2 });

subscribe

• matterbridge/deviceid/subscribe/root

Publish here only the attribute changes that the device wants to receive from the controller.

const subscribe = { OnOff: ['onOff'], LevelControl: ['currentLevel'] };
publish('matterbridge/deviceid/state/root', JSON.stringify(subscribe), { retain: true, qos: 2 });

Subscribe

Each device may subscribe to write messages:

subscribe('matterbridge/deviceid/write/root', { qos: 2 });

and will receive all attributes changes it subscribed to.

{ OnOff: { onOff: false }, LevelControl: { currentLevel: 254 } }

Test script

See src/test-publish.ts for working examples. It is a stand-alone helper that reads ~/.matterbridge/matterbridge-mqtt.config.json, connects to the configured MQTT broker, and publishes retained config, state and subscribe messages for every supported device type.

Run it after building:

node dist/test-publish.js

Parameters:

• --filter <name> — only publish devices whose name contains <name> (e.g. --filter Light for all device types including Light).
• --update — publish a changed state to the state topic of each device (state change only, no config or subscribe).
• --delete — publish empty retained payloads to clear the topics instead of publishing config/state/subscribe. It will remove the devices from Matterbridge (no restart needed).

---

Repository setup

Note: This repository uses a new toolchain. It replaces the traditional TypeScript / ESLint / Prettier / Jest stack with a faster, lighter setup.

• No typescript package — replaced by TypeScript Native. The typescript package is kept only as a publish-time dependency while tsgo is still in preview.
• No ESLint, no Prettier — replaced by the oxc stack: oxlint for linting and oxfmt for formatting.
• No Jest — replaced by Vitest, which is much faster and natively supports ESM without extra configuration.
• Far fewer development dependencies — the number of installed packages drops from ~600 to ~100. A clean install is much faster.
• Much faster linting and formatting — oxlint and oxfmt run in a fraction of the time required by the ESLint / Prettier pipeline.
• Much faster builds — tsgo compiles the project in a fraction of the time required by the standard tsc build.
• Editor support — use the VS Code extensions for tsgo and oxc to get the same experience in the editor.

Todo

• Add composed device types