MatterBridge for Home Assistant: Expose Any Device to Matter Controllers

Table of Contents

Video

Is your smart home split across ecosystems? MatterBridge turns your existing Home Assistant entities into native‑looking Matter devices so you can control Zigbee, Z‑Wave, Wi‑Fi, and MQTT devices from Apple Home, Google Home, or SmartThings. This guide walks you through setup plus copy‑paste configs you can use immediately.

What MatterBridge Does

Acts as a Matter “bridge” so non‑Matter devices appear as native Matter devices to other controllers
Works with Home Assistant via a MatterBridge add‑on and the matterbridge-hass plugin
Exposes lights, switches, sensors, fans, thermostats, scenes, and scripts
Lets you filter exactly which entities are exposed with areas, labels, whitelists, and blacklists

Requirements

Home Assistant OS or Supervised with Supervisor Add‑ons available
A Long‑Lived Access Token from your Home Assistant user profile
A Matter controller app for pairing, such as Apple Home or Google Home

1) Install the MatterBridge Add‑on

MatterBridge for Home Assistant: https://github.com/Luligu/matterbridge-hass

If the repository offers an “Open in Home Assistant” link, use it. Otherwise add the repo manually in Settings → Add‑ons → Add‑on Store → ⋮ → Repositories.

Start the add‑on after install
Open Web UI

Tip: If you prefer Docker on another host, use the compose file below.

# docker-compose.yml
services:
  matterbridge:
    image: [ghcr.io/luligu/matterbridge:latest](<http://ghcr.io/luligu/matterbridge:latest>)
    container_name: matterbridge
    restart: unless-stopped
    network_mode: host
    environment:
      - TZ=America/Chicago
    volumes:
      - ./matterbridge/data:/app/data

Run:

docker compose up -d

2) Install the Home Assistant Plugin inside MatterBridge

In the MatterBridge Web UI:

Go to Plugins
Install: matterbridge-hass
Open the plugin’s settings

You’ll need:

Home Assistant URL, for example: http://homeassistant.local:8123
A Long‑Lived Access Token

Create a token:

Home Assistant sidebar → Your user → Security → Long‑Lived Access Tokens → Create Token → Copy

Paste that token into the plugin config.

3) Pairing with Your Matter Controller

In MatterBridge’s main screen, view the QR and manual code
In your controller app:
- Apple Home: Add Accessory → More options → Scan QR or enter code
- Google Home: Devices → + Add → Set up a device → Works with Google → Matter/QR
After pairing, exposed entities appear as native devices in that app

Tip: If you change exposed entities, some controllers need a re‑sync or re‑pair. Try toggling exposure or restarting the bridge before removing and re‑adding.

4) Example: Office Govee Lights + Flic Duo

Goal: Use a Matter remote to control a Home Assistant light with no native Matter support.

Label your target entities in Home Assistant as “HomeBridge”
In the plugin config, filter by that label (here is a YAML example):

{
  "expose": {
    "filterByLabel": true,
    "labels": ["HomeBridge"],
    "applyFiltersToDeviceEntities": true
  }
}

Pair the bridge to your Flic LR Hub or Aqara M3/G5 controller
In the controller app, assign the exposed light to your remote’s button actions

7) Advanced Tips

Scenes as Matter Buttons:
- Add scene.entity_id to whiteList
- Controllers will show it as a triggerable control

Climate devices:
- Keep only “climate.*” in includeEntityDomains to simplify pairing
Reduce noise:
- Exclude “update”, “select”, “number”, and diagnostic sensors
Naming:
- Clean, human‑readable Home Assistant names become much nicer in controller apps

8) Troubleshooting

Pairing fails or code not shown:
- Restart the add‑on and the plugin
- Ensure only one bridge instance is running on the network
- Check that network_mode: host is used for Docker
Devices not appearing:
- Confirm filters aren’t hiding them
- Try a temporary whiteList to force exposure
- Reopen the controller app and refresh device list
Unwanted duplicate switches:
- Use deviceEntityBlackList to hide extras
- Use splitEntities to turn a sub‑entity into its own device when helpful
Token errors:
- Regenerate a Long‑Lived Token and re‑paste it
- Check baseUrl and connectivity to Home Assistant

Copy‑Paste Checklist

Create Long‑Lived Token in Home Assistant
Install MatterBridge add‑on or Docker
Install matterbridge-hass plugin and paste config
Start with Minimal Working Configuration
Apply filters: by Area or Label, or use whiteList
Pair with Apple Home or Google Home via QR
Adjust splitEntities and deviceEntityBlackList to clean up devices

Closing Thoughts

MatterBridge turns Home Assistant into a powerful interoperability layer for Matter ecosystems. With smart filtering and clean entity naming, you get a tidy, native‑feeling device list in Apple Home, Google Home, and more—without replacing your existing devices.