# io.github.alexpfau/zigbee2mqtt-mcp (npm · zigbee2mqtt-mcp)

Administer a Zigbee2MQTT estate: health, mesh diagnostics, OTA, pairing, device management.

- Trust score: 78/100 (medium)
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-12

## Components

- npm · `zigbee2mqtt-mcp`: 78/100 (this document), [markdown](https://verifymcp.io/servers/alexpfau-zigbee2mqtt-mcp/zigbee2mqtt-mcp.md), [page](https://verifymcp.io/servers/alexpfau-zigbee2mqtt-mcp/zigbee2mqtt-mcp)

## Channel facts

- Registry: `npm`
- Package: `zigbee2mqtt-mcp`
- Version: `0.7.0`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-12.

- **Supply Chain Security**: 98/100
  - No malware found by supply-chain analysis.
  - No known CVEs affecting this package version or its production dependencies.
  - No install/post-install scripts declared.
  - 52 of 137 dependencies flagged as unhealthy.
- **Provenance & Transparency**: 97/100
  - Source repository is publicly reachable at the declared URL.
  - Cryptographically verified build provenance (signed, bound to alexpfau/zigbee2mqtt-mcp).
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 4 days ago).
  - Security-disclosure policy not yet verified: we couldn't inspect the source repository.
- **Schema Quality & AI Usability**: 71/100
  - AI-judged instruction clarity (excellent).
  - Context-footprint check failed: tool/resource definitions use about 3112 tokens (~163/item across 19 items; 19 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 0/100
  - Stability not yet verified: not enough scan history yet (needs a 30-day window).
- **Tool Coverage**: 98/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 95% of tool parameters carry a description.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

**Unverified: 1 category.** A category scored 0 because we could not verify it: a data source with nothing on this package, evidence we could not reach, or a check we could not run. We only credit what we can confirm.

## Install

### Claude

```bash
claude mcp add alexpfau-zigbee2mqtt-mcp -- npx -y zigbee2mqtt-mcp
```

### Codex

```bash
codex mcp add alexpfau-zigbee2mqtt-mcp -- npx -y zigbee2mqtt-mcp
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "alexpfau-zigbee2mqtt-mcp": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "zigbee2mqtt-mcp"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add alexpfau-zigbee2mqtt-mcp --command npx --arg -y --arg zigbee2mqtt-mcp
```

### Hermes

```yaml
mcp_servers:
  alexpfau-zigbee2mqtt-mcp:
    command: "npx"
    args: ["-y", "zigbee2mqtt-mcp"]
```

### Other

```json
{
  "mcpServers": {
    "alexpfau-zigbee2mqtt-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "zigbee2mqtt-mcp"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-12 (score 78, 0)

- [functional regression] Security disclosure: pass → unverified

### 2026-08-11 (score 78, 0)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-08-08 (score 78, +39)

- [security improvement] Known CVEs: unverified → pass
- [security] Stability: Stability not yet verified: not enough scan history yet (needs a 30-day window).
- [functional improvement] Tool coverage: unverified → 100
- [functional improvement] Dependency health: unverified → 0.82
- [functional improvement] MCP protocol: unverified → pass
- [functional] First check of Schema quality: excellent
- [functional] First check of Schema quality: fail
- [functional] First check of Tool coverage: 95
- [functional] First check of Schema quality: fail

### 2026-08-07 (score 39)

First indexed and scored.

## MCP tools (19)

### `z2m_connection_status` (~133 tokens)

Check whether this server can reach the MQTT broker and whether Zigbee2MQTT is publishing to it. Read-only, and the only tool that reports rather than throws when the connection is down or not configured at all, so call it first when any other tool fails with a connection or timeout error. Distinguishes an unreachable broker from a reachable broker carrying no Zigbee2MQTT data, which usually means Z2M_BASE_TOPIC does not match the mqtt.base_topic setting in Zigbee2MQTT. Reports the broker URL with credentials redacted, TLS settings, cached message counts and the write mode.

### `z2m_bridge_info` (~129 tokens)

Get Zigbee2MQTT bridge status: version, coordinator type and firmware, Zigbee channel and PAN ID, permit_join state, log level, whether a restart is required, and host OS/memory. Read-only. Start here to understand the estate, then use z2m_health_report for problems or z2m_list_devices for individual devices. Returns a JSON object; set include_config only if you need the full Zigbee2MQTT configuration, which is large.

Input parameters:

- `include_config` (boolean): Include the full Zigbee2MQTT configuration (large). Default false.

### `z2m_list_devices` (~286 tokens)

List Zigbee devices with administrative detail: type, model, vendor, power source, link quality, battery, availability, last_seen, interview state and pending OTA updates. Read-only, though collect_seconds will wait before answering. Use this to answer 'which devices are offline' or 'which have the weakest signal'. Prefer z2m_health_report for a prioritised summary of everything wrong at once, and z2m_get_device when you need one device's exposes, options or bindings. Returns {total, returned, capabilities, devices[]}.

Input parameters:

- `availability` (string)
- `collect_seconds` (number): Listen for live device traffic for this many seconds before answering, to populate linkquality, battery and OTA fields that Zigbee2MQTT does not publish as retained messages. Max 120.
- `has_update` (boolean): Only devices with a pending OTA firmware update.
- `limit` (number): Maximum number of devices to return.
- `only_problems` (boolean): Only devices that are offline, disabled, unsupported, mid-interview, weak-signal or low-battery.
- `search` (string): Case-insensitive substring match on name, model, vendor or description.
- `sort_by` (string): Default friendly_name. Numeric sorts are ascending, so weakest/lowest first.
- `type` (string): Filter by Zigbee device type.

### `z2m_get_device` (~120 tokens)

Get full detail for one device: current state, exposed properties, configurable device options with their schema, endpoints, bindings and configured reportings. Read-only. Call this before z2m_set_device_options, z2m_bind or z2m_configure_reporting to discover valid values. Use z2m_list_devices instead when you want many devices or do not know the exact name.

Input parameters:

- `device` (string, required): Device friendly_name or ieee_address.
- `include_raw` (boolean): Include the raw exposes/options definitions (verbose). Default false.

### `z2m_health_report` (~187 tokens)

Audit the whole Zigbee estate in one call and return everything that needs attention: offline devices, weak links, stale devices, low batteries, failed or pending interviews, unsupported devices, disabled devices, pending OTA updates, and devices that keep rejoining or changing network address. Read-only and generates no Zigbee traffic, so prefer it over z2m_check_updates and z2m_network_map for routine checks. Use this to answer 'is my Zigbee network healthy?'. Returns {bridge, totals, capabilities, issues, hints}; an empty issues object means nothing is wrong. Note that collect_seconds makes the call wait for that many seconds before answering.

Input parameters:

- `collect_seconds` (number): Listen for live device traffic for this many seconds before answering, to populate linkquality, battery and OTA fields that Zigbee2MQTT does not publish as retained messages. Max 120.

### `z2m_network_map` (~177 tokens)

Scan the Zigbee mesh topology and return per-device parent, depth, link quality and route count, plus orphaned or weakly-attached devices. WARNING: the scan makes the network less responsive and can take 10 seconds to several minutes depending on estate size. Run it deliberately, not routinely, and prefer z2m_health_report or z2m_list_devices when you only need per-device link quality. Returns {node_count, link_count, orphans, weak, nodes[]} unless raw is set.

Input parameters:

- `include_routes` (boolean): Include active routes. Slower. Default false.
- `max_nodes` (number): Cap the nodes returned. Default 200.
- `raw` (boolean): Return the unsummarised graph. Default false.
- `timeout_ms` (number): Scan timeout. Default 180000.

### `z2m_list_groups` (~60 tokens)

List Zigbee groups with their members and scenes. Read-only. Use z2m_manage_group to change groups, and z2m_list_devices for individual devices. Returns {total, groups[]}; an empty list means no groups are defined.

### `z2m_get_logs` (~205 tokens)

Read Zigbee2MQTT bridge logs and lifecycle events (device_joined, device_interview, device_leave, device_announce). Read-only. Returns buffered history by default; watch_seconds instead blocks for that many seconds collecting new lines. Logs are only captured while this server is connected, so history may be empty on a fresh start — use watch_seconds then. Use to diagnose pairing failures and rejoin loops; prefer z2m_health_report to find which devices are affected in the first place.

Input parameters:

- `contains` (string): Only lines containing this substring (case-insensitive).
- `include_events` (boolean): Include bridge lifecycle events. Default true.
- `level` (string): Minimum severity. Note: Zigbee2MQTT never publishes debug lines to MQTT.
- `limit` (number): Maximum lines to return. Default 100.
- `watch_seconds` (number): Collect new lines live for this many seconds instead of returning buffered history. Max 120.

### `z2m_coordinator_check` (~120 tokens)

Check whether any routers are missing from the coordinator's memory, which causes pairing failures and devices dropping off. Changes nothing, but queries the coordinator directly. Needs an adapter that supports coordinator backups, which Texas Instruments zStack and Silicon Labs EmberZNet do and deCONZ and ZiGate do not; unsupported adapters return an error, and z2m_bridge_info reports the expectation under capabilities.coordinator_check. Returns {missing_routers[]}; an empty list is healthy. Use z2m_network_map for a topology view on any adapter.

### `z2m_check_updates` (~170 tokens)

Actively query devices for available OTA firmware updates. Changes no configuration, but it does put real traffic on the Zigbee network and can take a minute per device. Without arguments it checks every mains-powered router. Prefer z2m_health_report for a passive answer at no network cost, and use this only when you need a fresh check. Follow with z2m_ota_update to actually flash.

Input parameters:

- `device` (string): Check a single device. Omit to check all mains-powered devices.
- `max_devices` (number): Stop after this many devices so the call returns before a client times out. Default 10.
- `offset` (number): Skip this many devices, to continue a previous sweep.
- `timeout_ms` (number): Per-device timeout. Default 60000.

### `z2m_permit_join` (~139 tokens)

Open or close the network for new devices to join. While open, any nearby Zigbee device may join, so keep the window short and close it with time=0 when finished. Optionally scope joining to a single router, which is the recommended way to pair a device into a specific part of the mesh. Use z2m_bridge_info to see whether joining is currently open.

Input parameters:

- `device` (string): Restrict joining to this router's friendly_name, or 'coordinator'. Omit to allow via any router.
- `time` (number, required): Seconds to allow joining. 0 closes the network. Maximum 254.

### `z2m_set_device_options` (~141 tokens)

Change Zigbee2MQTT device options such as transition, retain, debounce, temperature_precision or calibration offsets. Options are merged, not replaced, and persist in the Zigbee2MQTT configuration. Call z2m_get_device first to see settable_options for that device. Use z2m_set_state to change what a device is doing, and z2m_set_bridge_options for bridge-wide settings. The response reports whether a bridge restart is required.

Input parameters:

- `device` (string, required): Device friendly_name or ieee_address.
- `options` (object, required): Options to merge, e.g. {"transition": 1, "retain": true}.

### `z2m_rename_device` (~134 tokens)

Rename a device's friendly_name. Renaming changes its MQTT topic, so anything referencing the old name (automations, dashboards, scripts) breaks until updated — this is reversible only by renaming back. Set homeassistant_rename to also rename the Home Assistant entity. Use z2m_set_device_options for behaviour changes that do not affect the topic.

Input parameters:

- `device` (string, required): Device friendly_name or ieee_address.
- `homeassistant_rename` (boolean): Also update the Home Assistant entity ID. Default false.
- `new_name` (string, required): New friendly_name. '/' creates folder structure in MQTT.

### `z2m_configure_device` (~106 tokens)

Re-run a device's configuration routine (bindings and attribute reporting). Use when a device stopped reporting values. Battery devices must be woken immediately before calling this, or it fails after a timeout. Use z2m_interview_device instead when Zigbee2MQTT does not know the device's capabilities at all, and z2m_configure_reporting to change one specific attribute rather than re-running everything.

Input parameters:

- `device` (string, required): Device friendly_name or ieee_address.

### `z2m_interview_device` (~111 tokens)

Re-interview a device so Zigbee2MQTT re-reads its endpoints, clusters and basic attributes. The device may be briefly unavailable while this runs, and battery devices must be awake. Useful after a firmware upgrade adds functionality, or to recover a device stuck in a failed interview — check interview_state via z2m_get_device first. Use z2m_configure_device instead when the interview succeeded but reporting stopped working.

Input parameters:

- `device` (string, required): Device friendly_name or ieee_address.

### `z2m_set_state` (~156 tokens)

Send a state command to a device or group, e.g. {"state":"ON"} or {"brightness":128}. Physically changes what the device is doing, and is reversible by sending the opposite command. mode='get' instead requests a value without changing anything. The command is published without waiting for the device, so success here means the message was sent, not that the device acted — read z2m_get_device afterwards to confirm. Consult z2m_get_device exposes for valid properties.

Input parameters:

- `device` (string, required): Device or group friendly_name, or ieee_address.
- `mode` (string): Default 'set'.
- `payload` (object, required): Command payload, e.g. {"state": "ON"}.

### `z2m_manage_group` (~243 tokens)

Create or remove groups, rename them, and add or remove device members. Groups let a single Zigbee multicast control many devices, which is far more responsive than commanding each device in turn. Removing a group does not affect the devices themselves, but fails if a member is unreachable unless force is set — with force the device keeps the group membership internally. Use z2m_list_groups to inspect groups first, and z2m_set_state to control a group once created. The remove and remove_all_members actions discard configuration and need confirm=true.

Input parameters:

- `action` (string, required)
- `confirm` (boolean): Required for action=remove and action=remove_all_members.
- `device` (string): Device for member actions.
- `endpoint` (string|number): Endpoint for member actions, e.g. 'l1' or 1. Defaults to the device's default endpoint.
- `force` (boolean): Force removal even if a member device is unreachable.
- `group` (string, required): Group friendly_name or numeric ID.
- `id` (number): Optional numeric ID for action=add.
- `new_name` (string): Required for action=rename.

### `z2m_bind` (~287 tokens)

Bind or unbind clusters between two devices, or between a device and a group. Binding lets a remote control a light directly over Zigbee without a round trip through the coordinator, so it keeps working even if the bridge is down. Reversible with action='unbind'; action='clear' removes all binds from the source device at once and needs confirm=true, because the previous set cannot be recovered. To target one button of a multi-button remote, pass from_endpoint and to_endpoint as separate arguments — check z2m_get_device endpoints first. Both devices must be awake.

Input parameters:

- `action` (string, required)
- `clusters` (array): Clusters to bind, e.g. ['genOnOff','genLevelCtrl']. Omit to bind all supported clusters.
- `confirm` (boolean): Required for action=clear.
- `from` (string, required): Source device friendly_name or ieee_address.
- `from_endpoint` (string|number): Source endpoint, e.g. 'left' or 1. Defaults to the device's default endpoint.
- `ieee_list` (array): For action=clear: specific bind targets to remove. Omit to clear every binding.
- `to` (string): Target device or group. Not needed for action=clear.
- `to_endpoint` (string|number): Target endpoint. Only meaningful when the target is a device, not a group.

### `z2m_configure_reporting` (~208 tokens)

Configure how often a device reports an attribute. Tightening intervals improves responsiveness; loosening them saves battery. Set maximum_report_interval to 65535 to disable reporting. Battery devices must be woken immediately before calling this, and not all devices support the command. Use z2m_get_device to see existing configured_reportings, and z2m_configure_device to re-run the whole default configuration instead of one attribute.

Input parameters:

- `attribute` (string, required): Attribute name, e.g. 'currentLevel'.
- `cluster` (string, required): Cluster name, e.g. 'genLevelCtrl'.
- `device` (string, required): Device friendly_name or ieee_address.
- `endpoint` (number): Endpoint ID. Default 1.
- `maximum_report_interval` (number, required): Seconds. 65535 disables reporting.
- `minimum_report_interval` (number, required): Seconds. 0 means report on every change.
- `reportable_change` (number): Minimum change worth reporting, in the attribute's unit.

## Diagnostics

Captured diagnostic sections: Provenance, Dependencies. The full working is on the page: https://verifymcp.io/servers/alexpfau-zigbee2mqtt-mcp/zigbee2mqtt-mcp#diagnostics

## Score history

- 2026-08-12: 78
- 2026-08-11: 78
- 2026-08-10: 78
- 2026-08-09: 78
- 2026-08-08: 78
- 2026-08-07: 39

## Links

- npm package: https://www.npmjs.com/package/zigbee2mqtt-mcp
- Socket report: https://socket.dev/npm/package/zigbee2mqtt-mcp
- Repository: https://github.com/alexpfau/zigbee2mqtt-mcp
- Changelog RSS feed: https://verifymcp.io/servers/alexpfau-zigbee2mqtt-mcp/zigbee2mqtt-mcp.xml
- Changelog JSON feed: https://verifymcp.io/servers/alexpfau-zigbee2mqtt-mcp/zigbee2mqtt-mcp.json
- HTML version of this page: https://verifymcp.io/servers/alexpfau-zigbee2mqtt-mcp/zigbee2mqtt-mcp