io.github.alexpfau/zigbee2mqtt-mcp

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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[]}.

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.

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.

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.

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.

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.

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.

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.