---
id: matter-ble-proxy
version: "1.4.0"
license: Apache-2.0
license_treatment: permissive
maintenance: active
---

# matter-ble-proxy — Python client library for the OHF Matter Server BLE proxy protocol

License: permissive · Maintenance: active · Downloads: 79.5K/mo

## What it is and what it does

matter-ble-proxy is a Python client library that implements the OHF Matter Server's BLE proxy protocol, enabling a Matter Server running on a host without a BLE adapter to delegate Bluetooth operations to a separate process or device. It sits between a local BLE source and a remote Matter Server's `/ble` WebSocket endpoint, translating BLE scan results and device operations into the proxy protocol.

The library provides both a standalone CLI tool for testing and a pluggable library API. Integrators implement two abstract base classes—BleScanSource (to feed BLE advertisements) and BleDeviceResolver (to resolve device addresses)—then instantiate MatterBleProxy with a WebSocket URL and those implementations. The library deliberately does not manage reconnection; it releases all BLE resources and returns control when the WebSocket closes, leaving retry logic to the caller's supervisor.

Use it for:

- Run a Matter Server on a host with no Bluetooth adapter while delegating BLE operations to a separate device with a BLE radio.
- Integrate Matter BLE bridging into Home Assistant by wiring its native Bluetooth component as the scan source and device resolver.
- Build a custom Matter gateway that aggregates BLE devices from multiple physical locations by running proxy instances on each site.
- Test a Matter Server's `/ble` endpoint in isolation without a full Home Assistant deployment using the bundled CLI.
- Implement a BLE proxy for home automation systems that need to speak Matter protocol over a network boundary.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

A Python client library that bridges BLE operations to a remote Matter Server via WebSocket, allowing any process with a BLE adapter to act as a BLE proxy for Matter protocol communication.

Yes, if you are building or integrating with a Matter Server and need to separate BLE hardware from the server host. The library is actively maintained, has low install friction, carries a permissive Apache-2.0 license, and is designed for exactly this delegation pattern. Not relevant if your Matter Server and BLE adapter are on the same machine or if you do not need Matter protocol support.

## Install

pip install matter-ble-proxy
uv add matter-ble-proxy
poetry add matter-ble-proxy

## Installing matter-ble-proxy

Before you install: Low friction: pure Python wheel with only two runtime dependencies (aiohttp, bleak). Active maintenance with a release 7 days old. Requires Python 3.12+, which is a hard constraint but clearly stated.

License in practice: Apache-2.0 permissive license allows commercial and private use with minimal restrictions; suitable for most integration scenarios including proprietary systems.

Quickstart:

pip install matter-ble-proxy

from matter_ble_proxy import MatterBleProxy, BleScanSource, BleDeviceResolver

proxy = MatterBleProxy(
    ws_url="ws://localhost:5580/ble",
    scan_source=MyScanSource(),
    device_resolver=MyDeviceResolver(),
)
await proxy.connect()
await proxy.run_until_closed()

Requires Python 3.12+. Caller must implement BleScanSource and BleDeviceResolver abstract base classes; default Bleak-backed implementations are available in matter_ble_proxy.bleak_backend.

Verify before relying:

- Whether the library handles reconnection automatically or requires caller-managed retry logic.
- Performance characteristics and latency overhead of the WebSocket proxy layer compared to direct BLE access.
- Compatibility with specific Matter Server versions or protocol versions.

## Package facts

- License: Apache-2.0 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 79.5K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

matter server ble proxy client, bluetooth matter protocol bridge, remote ble adapter websocket, matter ble delegation, websocket proxy bluetooth, matter server ble endpoint, distributed bluetooth gateway, matter-protocol, ble-proxy, home-automation

[View on SkillFed](https://skillfed.io/packages/matter-ble-proxy) · [View on PyPI](https://pypi.org/project/matter-ble-proxy/)