{"id":14985319,"url":"https://github.com/luligu/matterbridge-zigbee2mqtt","last_synced_at":"2026-02-20T22:27:04.386Z","repository":{"id":229286581,"uuid":"763009356","full_name":"Luligu/matterbridge-zigbee2mqtt","owner":"Luligu","description":"Matterbridge zigbee2mqtt plugin","archived":false,"fork":false,"pushed_at":"2025-03-19T21:24:19.000Z","size":1219,"stargazers_count":103,"open_issues_count":6,"forks_count":11,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-12T23:16:51.567Z","etag":null,"topics":["alexa","bridge","connectedthings","google-home","homeassistant","homekit","iot","matter","matterbridge","matterprotocol","plugin","siri","smarthome","zigbee","zigbee2mqtt"],"latest_commit_sha":null,"homepage":"https://github.com/Luligu/matterbridge-zigbee2mqtt/blob/main/README.md","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Luligu.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":"luligugithub","custom":null}},"created_at":"2024-02-25T10:12:39.000Z","updated_at":"2025-04-09T04:25:01.000Z","dependencies_parsed_at":"2024-04-23T12:10:30.899Z","dependency_job_id":"3481d167-0dfd-4ed2-b0cf-9d51224b4d0f","html_url":"https://github.com/Luligu/matterbridge-zigbee2mqtt","commit_stats":{"total_commits":246,"total_committers":2,"mean_commits":123.0,"dds":0.004065040650406471,"last_synced_commit":"79f6d9280fd3e123dd48e3cb49be4114824294d3"},"previous_names":["luligu/matterbridge-zigbee2mqtt"],"tags_count":53,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Luligu%2Fmatterbridge-zigbee2mqtt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Luligu%2Fmatterbridge-zigbee2mqtt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Luligu%2Fmatterbridge-zigbee2mqtt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Luligu%2Fmatterbridge-zigbee2mqtt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Luligu","download_url":"https://codeload.github.com/Luligu/matterbridge-zigbee2mqtt/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248681493,"owners_count":21144700,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alexa","bridge","connectedthings","google-home","homeassistant","homekit","iot","matter","matterbridge","matterprotocol","plugin","siri","smarthome","zigbee","zigbee2mqtt"],"created_at":"2024-09-24T14:10:42.275Z","updated_at":"2026-02-07T13:07:40.945Z","avatar_url":"https://github.com/Luligu.png","language":"TypeScript","funding_links":["https://buymeacoffee.com/luligugithub","https://www.buymeacoffee.com/luligugithub"],"categories":[],"sub_categories":[],"readme":"# \u003cimg src=\"https://matterbridge.io/assets/matterbridge.svg\" alt=\"Matterbridge Logo\" width=\"64px\" height=\"64px\"\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;Matterbridge zigbee2mqtt plugin\n\n[![npm version](https://img.shields.io/npm/v/matterbridge-zigbee2mqtt.svg)](https://www.npmjs.com/package/matterbridge-zigbee2mqtt)\n[![npm downloads](https://img.shields.io/npm/dt/matterbridge-zigbee2mqtt.svg)](https://www.npmjs.com/package/matterbridge-zigbee2mqtt)\n[![Docker Version](https://img.shields.io/docker/v/luligu/matterbridge/latest?label=docker%20version)](https://hub.docker.com/r/luligu/matterbridge)\n[![Docker Pulls](https://img.shields.io/docker/pulls/luligu/matterbridge?label=docker%20pulls)](https://hub.docker.com/r/luligu/matterbridge)\n![Node.js CI](https://github.com/Luligu/matterbridge-zigbee2mqtt/actions/workflows/build.yml/badge.svg)\n![CodeQL](https://github.com/Luligu/matterbridge-zigbee2mqtt/actions/workflows/codeql.yml/badge.svg)\n[![codecov](https://codecov.io/gh/Luligu/matterbridge-zigbee2mqtt/branch/main/graph/badge.svg)](https://codecov.io/gh/Luligu/matterbridge-zigbee2mqtt)\n[![styled with prettier](https://img.shields.io/badge/styled_with-Prettier-f8bc45.svg?logo=prettier)](https://github.com/prettier/prettier)\n[![linted with eslint](https://img.shields.io/badge/linted_with-ES_Lint-4B32C3.svg?logo=eslint)](https://github.com/eslint/eslint)\n[![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript\u0026logoColor=white)](https://www.typescriptlang.org/)\n[![ESM](https://img.shields.io/badge/ESM-Node.js-339933?logo=node.js\u0026logoColor=white)](https://nodejs.org/api/esm.html)\n[![matterbridge.io](https://img.shields.io/badge/matterbridge.io-online-brightgreen)](https://matterbridge.io)\n\n[![powered by](https://img.shields.io/badge/powered%20by-matterbridge-blue)](https://www.npmjs.com/package/matterbridge)\n[![powered by](https://img.shields.io/badge/powered%20by-matter--history-blue)](https://www.npmjs.com/package/matter-history)\n[![powered by](https://img.shields.io/badge/powered%20by-node--ansi--logger-blue)](https://www.npmjs.com/package/node-ansi-logger)\n[![powered by](https://img.shields.io/badge/powered%20by-node--persist--manager-blue)](https://www.npmjs.com/package/node-persist-manager)\n\n---\n\nMatterbridge zigbee2mqtt is a matterbridge production-level plugin that expose all zigbee2mqtt devices and groups to Matter. Scenes are supported too.\n\nNo hub or dedicated hardware needed.\n\nNo cloud: all is local and fast.\n\nThe connection to the MQTT broker is possible with **mqtt** (tcp), **mqtts** (tls), **mqtt+unix** (Unix socket), **ws** (web socket) and **wss** (secure web socket). Self signed certificates and mutual tls are supported too.\n\nInterested in super fast and autonomous **[automations for zigbee2mqtt](https://github.com/Luligu/zigbee2mqtt-automations)**? Try this: https://github.com/Luligu/zigbee2mqtt-automations.\n\nIf you like this project and find it useful, please consider giving it a star on [GitHub](https://github.com/Luligu/matterbridge-zigbee2mqtt) and sponsoring it.\n\n\u003ca href=\"https://www.buymeacoffee.com/luligugithub\"\u003e\u003cimg src=\"https://matterbridge.io/assets/bmc-button.svg\" alt=\"Buy me a coffee\" width=\"120\"\u003e\u003c/a\u003e\n\n## Introduction\n\nMatterbridge enables non-Matter devices (Zigbee devices) to integrate with the Matter communication protocol. Bridges allow platforms that use other protocol standards to interoperate with the Matter ecosystem by integrating a Matter server into, or between, existing smart gateways, controllers, and hubs. Many commercial smart gateways provide a built-in Matter bridge that translates Matter to Zigbee or other protocols, making it possible for other ecosystems to communicate with them.\n\nThe Matterbridge zigbee2mqtt plugin acts as a Matter Bridge, exposing all Zigbee devices, groups and scenes from [Zigbee2MQTT](https://github.com/Koenkk/zigbee2mqtt/blob/master/README.md) as Matter devices to third-party Matter controllers like Apple Home, Google Home, Amazon Alexa, and SmartThings, all while remaining local on the user's network. This allows fast, secure, and cloud-free control of Zigbee2MQTT-connected Zigbee devices from all major voice assistants as well as other third-party Matter clients.\n\n## Prerequisites\n\n### Matterbridge\n\nSee the guidelines on [Matterbridge](https://matterbridge.io/README.html) for more information.\n\n### Zigbee2mqtt\n\nSee the guidelines on [zigbee2mqtt](https://www.zigbee2mqtt.io/) for more information.\n\n## How to install the plugin\n\n### With the frontend (preferred method)\n\nJust open the frontend, select the matterbridge-zigbee2mqtt plugin and click on install. If you are using Matterbridge with Docker (I suggest you do it), all plugins are already loaded in the container so you just need to select and add it.\n\n### Without the frontend\n\nOn windows:\n\n```\ncd $HOME\\Matterbridge\nnpm install -g matterbridge-zigbee2mqtt --omit=dev\nmatterbridge -add matterbridge-zigbee2mqtt\n```\n\nOn linux and macOS:\n\n```\ncd ~/Matterbridge\nsudo npm install -g matterbridge-zigbee2mqtt --omit=dev\nmatterbridge -add matterbridge-zigbee2mqtt\n```\n\nThen start Matterbridge\n\n```\nmatterbridge\n```\n\n## If you want to contribute to the plugin\n\nClone the plugin\n\n```\ncd ~/Matterbridge\ngit clone https://github.com/Luligu/matterbridge-zigbee2mqtt\ncd matterbridge-zigbee2mqtt\nnpm ci\nnpm run dev:link\nnpm run build\nmatterbridge -add .\n```\n\nThen start Matterbridge\n\n```\nmatterbridge\n```\n\n# Config file\n\nAll configurations can (and should) be done with the frontend.\n\nIf needed you can configure the mqtt host, port, topic, username and password.\n\nIf the whiteList is defined only the devices included are exposed to Matter.\n\nIf the blackList is defined the devices included will not be exposed to Matter.\n\nIf any device creates issues put it in the blackList.\n\nThe switchList, lightList and outletList are used if you want to expose the z2m device like switch, light or outlet.\n\nThe featureBlackList allows to globally (for all devices) blacklist a z2m feature if you don't want to expose it (e.g. device_temperature).\n\nThe deviceFeatureBlackList allows to blacklist a z2m feature for a single device if you don't want to expose it (e.g. temperature for a motion sensor).\n\nThe scenesType enable and set how to expose the scenes.\n\nThe scenesPrefix enable the prefix with device/grop name to the scene device.\n\nThe debug option allows to set the debug mode only for the plugin.\n\nThe unregisterOnShutdown option allows to remove from the bridge all z2m devices when you shut down Matterbridge.\n\nThese are the default vules:\n\n```json\n{\n  \"name\": \"matterbridge-zigbee2mqtt\",\n  \"type\": \"DynamicPlatform\",\n  \"version\": \"3.0.0\",\n  \"host\": \"mqtt://localhost\",\n  \"port\": 1883,\n  \"protocolVersion\": 5,\n  \"topic\": \"zigbee2mqtt\",\n  \"username\": \"\",\n  \"password\": \"\",\n  \"clientId\": \"\",\n  \"ca\": \"\",\n  \"cert\": \"\",\n  \"key\": \"\",\n  \"rejectUnauthorized\": true,\n  \"whiteList\": [],\n  \"blackList\": [],\n  \"switchList\": [],\n  \"lightList\": [],\n  \"outletList\": [],\n  \"featureBlackList\": [],\n  \"deviceFeatureBlackList\": {},\n  \"scenesType\": \"outlet\",\n  \"scenesPrefix\": true,\n  \"postfix\": \"\",\n  \"debug\": false,\n  \"unregisterOnShutdown\": false\n}\n```\n\nIf you want to exclude \"device_temperature\" for all the devices, add to the config\n\n```json\n{\n  ...\n  \"featureBlackList\": [\"device_temperature\"]\n  ...\n}\n```\n\nIf you want to exclude \"temperature\" and \"humidity\" for the device \"My motion sensor\" and\n\"device_temperature\" only for the device \"My climate sensor\", add to the config\n\n```json\n{\n  ...\n  \"deviceFeatureBlackList\": {\n    \"My motion sensor\": [\"temperature\", \"humidity\"],\n    \"My climate sensor\": [\"device_temperature\"]\n  }\n  ...\n}\n```\n\nFrom the release 1.2.14 of Matterbridge you can edit the config file directly in the frontend. I strongly suggest you use the integrated config editor.\n\nYou can edit the config file manually if you prefer:\n\n- shutdown Matterbridge before: if you use docker send docker stop matterbridge;\n- edit and save the config;\n- start Matterbridge: if you use docker send docker start matterbridge.\n\nOn windows:\n\n```\ncd $HOME\\.matterbridge\nnotepad matterbridge-zigbee2mqtt.config.json\n```\n\nOn linux:\n\n```\ncd ~/.matterbridge\nnano matterbridge-zigbee2mqtt.config.json\n```\n\n# Frequently Asked Questions\n\n## What is supported?\n\nOut of the box, this plugin supports all possible conversion from zigbee2mqtt to Matter 1.4.\n\nIt also supports all clusters in the multi endpoints devices (e.g. DIY devices or the double channel switches/dimmers).\n\nSince the Matter support in the available ecosystems (controllers) is sometimes limited and, when available, only covers Matter 1.2 specifications, some z2m devices cannot be exposed properly or cannot be exposed at all.\n\n## Scenes in groups and devices\n\nWith release 2.5.0 has been added support for scenes in groups and devices.\n\nIn the config select what device type you want to use to expose the command that runs the scene: 'light' | 'outlet' | 'switch' | 'mounted_switch'.\n\nSwitch is not supported by Alexa. Mounted Switch is not supported by Apple Home.\n\nThe virtual device takes the name of the group or device it belongs to, with added the name of scene. If scenesPrefix is disabled, it takes only the name of the scene. Consider that in Matter the node name is 32 characters long. Consider also that each scene name must by unique if scenesPrefix is disabled.\n\nThe state of the virtual device is always reverted to off in a few seconds.\n\nIt is possibile to disable the feature globally with featureBlackList (add \"scenes\" to the list) and on a per device/group base with deviceFeatureBlackList (add \"scenes\" to the list).\n\n## Availability\n\nIf the availability is enabled in zigbee2mqtt settings, it is used to set the corresponding device/group reachable or not.\n\n[Screenshot](https://github.com/user-attachments/assets/7e0d395f-19e4-4e7f-b263-0cae3df70be4)\n\n## Retain\n\nIf the retain option is enabled in zigbee2mqtt settings or device setting, at restart all retained states are updated. I suggest to use this option expecially for battery powered devices.\n\nTo enable retain globally, stop zigbee2mqtt, add retain: true to device_options and restart zigbee2mqtt.\n\n```\ndevice_options:\n  retain: true\n```\n\nTo enable retain for a single device set it in the device settings.\n\n[Screenshot](https://github.com/user-attachments/assets/5ae09f2a-6cff-4623-92f4-87f7721ee443)\n\n## Unsupported devices\n\nIf one of your devices is not supported out of the box, open an issue and we will try to support it if possible.\n\n## Conversion strategies between zigbee2MQTT and Matter ecosystems\n\n- The Coordinator and the dedicated routers (Texas.Instruments and SMLIGHT) are exposed like DoorLock. They change state when permitJoin is changed from z2m and turn on or off permitJoin when they are opened or closed from the controller. If you don't want to see them in the controller app just add them to the blackList.\n\n- Scene buttons are now fully exposed (all actions). The actions are mapped in groups of 3, with each group on a sub endpoint. This is because the controllers expose event in group of single, double, long press.\n  In the log you will find the mapping schema like this one:\n\n```\n[16:25:14.321] [Smart button] Device Smart button has actions mapped to these switches on sub endpoints:\n[16:25:14.321] [Smart button]    controller events      \u003c=\u003e zigbee2mqtt actions\n[16:25:14.322] [Smart button] -- Button 1: Single Press \u003c=\u003e single\n[16:25:14.323] [Smart button] -- Button 1: Double Press \u003c=\u003e double\n[16:25:14.323] [Smart button] -- Button 1: Long Press   \u003c=\u003e hold\n[16:25:14.323] [Smart button] -- Button 2: Single Press \u003c=\u003e brightness_move_to_level\n[16:25:14.324] [Smart button] -- Button 2: Double Press \u003c=\u003e color_temperature_move\n[16:25:14.324] [Smart button] -- Button 2: Long Press   \u003c=\u003e brightness_step_up\n[16:25:14.324] [Smart button] -- Button 3: Single Press \u003c=\u003e brightness_step_down\n[16:25:14.324] [Smart button] -- Button 3: Double Press \u003c=\u003e on\n[16:25:14.325] [Smart button] -- Button 3: Long Press   \u003c=\u003e off\n```\n\n![See the screenshot here](https://github.com/Luligu/matterbridge-zigbee2mqtt/blob/main/screenshots/Smart%20button.png)\n\n## Unix socket (Linux only)\n\n**Note**: Unix domain sockets (mqtt+unix://) are always local and do not support TLS. Security is enforced through filesystem permissions on the socket file.\n\n### Create the directory for the Unix socket on the host\n\n```bash\n# Create the directory for the Unix socket if it doesn't exist\nsudo mkdir -p /var/run/mosquitto\n\n# Make sure the mosquitto user can access the socket\nsudo chown mosquitto:mosquitto /var/run/mosquitto\n\n# Allow group users (e.g. matterbridge) to access the socket\nsudo chmod 750 /var/run/mosquitto\n\n# Add your user to the mosquitto group to access the socket without sudo\nsudo usermod -aG mosquitto $USER\n\n# If matterbridge runs like user matterbridge, add the matterbridge user to the mosquitto group to access the socket without sudo\nsudo usermod -aG mosquitto matterbridge\n```\n\nLog out and back in after running usermod -aG for the group changes to take effect.\n\n```bash\n# Check the appropriate permissions for the directory\nsudo -u mosquitto ls -ld /var/run/mosquitto\nsudo -u mosquitto ls -l /var/run/mosquitto/mqtt.sock\n```\n\n### Configure mosquitto to use Unix socket on the host\n\nAdd this to your mosquitto.conf\n\n```\n# Unix socket listener\nlistener 0 /var/run/mosquitto/mqtt.sock\nprotocol mqtt\nallow_anonymous false\n```\n\nRestart mosquitto.\n\n```bash\nsudo systemctl restart mosquitto\n```\n\n### Configure docker to use Unix socket\n\nCreate the directory on the host\n\n```bash\nmkdir -p \"$HOME/mosquitto/run\"\nsudo chown 1883:1883 \"$HOME/mosquitto/run\"\nsudo chmod 770 \"$HOME/mosquitto/run\"\n```\n\nAdd the unix socket volume for each service using it (i.e. mosquitto, zigbee2mqtt and matterbridge).\n\n```\n  volumes:\n    - \"${HOME}/mosquitto/run:/var/run/mosquitto\"\n```\n\n# Known issues\n\nFor general controller issues check the Matterbridge Known issues section\n\n[See the known issues here](https://github.com/Luligu/matterbridge?tab=readme-ov-file#known-general-issues)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluligu%2Fmatterbridge-zigbee2mqtt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fluligu%2Fmatterbridge-zigbee2mqtt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluligu%2Fmatterbridge-zigbee2mqtt/lists"}