Home Assistant MCP Server

Official

by homeassistant-ai

Overview Schema Source Related Servers Discussions Admin

Python

Remote

Manage Radios (Z-Wave / Zigbee / Matter / Thread)

ha_manage_radio

Destructive

Manage Home Assistant Z-Wave, Zigbee, Matter, and Thread radios: run diagnostics, ping nodes, add or remove devices, reconfigure, update firmware, and read config parameters.

Instructions

Manage Home Assistant radios — Z-Wave, Zigbee, Matter, and Thread.

For node diagnostics and network summaries prefer ha_get_device / ha_get_system_health, which mirror 'diagnostics' and 'network_status'. This tool also exposes active 'ping' probes and parameter reads. Z-Wave 'get_config_params' lists cached configuration values/metadata; 'get_config_param' reads one from the cache or explicitly from the device. Neither enables or creates entities. Write actions perform inclusion/commissioning, removal, healing, reconfiguration, firmware updates and credential provisioning.

Caveats: long-running actions (inclusion, rebuild routes, firmware) start the operation and return immediately with long_running=true; completion happens out-of-band. Interactive Z-Wave S2 secure inclusion (read-the- PIN pairing) is not scriptable — use SmartStart/QR provisioning here or the HA UI. HA administrator access is required for parameter reads.

If a Claude Desktop user gets a 4-minute timeout with no result on this call, read the target back before repeating it, and tell them to wait a few seconds before clicking the manual-approve button, as clicking it too quickly is known to cause hangs in Claude Desktop. This workaround is specific to Claude Desktop.

Input Schema

Name	Required	Description
`radio`	Yes	Which radio to manage.
`action`	Yes	Operation to perform. Actions vary per radio; an unknown action returns the supported list for that radio. Common: 'diagnostics', 'network_status', 'ping', 'add'/'commission', 'remove_device', 'reinterview'/'reconfigure', 'firmware_update'.
`params`	No	Action-specific parameters (e.g. code, pin, channel, property, value). Z-Wave get_config_param: property (parameter number), endpoint (default 0), property_key (partial-parameter bit mask), refresh (default False; full root parameters only).
`confirm`	No	Required (True) to run destructive actions (e.g. remove_device, network restore, change_channel, hard_reset, remove_fabric).
`device_id`	No	Target device (node) for node-scoped actions.
`entity_id`	No	Resolve the device from this entity for node-scoped actions.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv8.7.0Oct 15, 2026

changedInput schema / properties / params / description

Previous value: -"Action-specific parameters (e.g. code, pin, channel, property, value)."New value: +"Action-specific parameters (e.g. code, pin, channel, property, value). Z-Wave get_config_param: property (parameter number), endpoint (default 0), property_key (partial-parameter bit mask), refresh (default False; full root parameters only)."

Changed2 schema fields changedv8.6.0Oct 1, 2026

changedInput schema / properties / confirm / description

Previous value: -"Required (True) to run destructive actions."New value: +"Required (True) to run destructive actions (e.g. remove_device, network restore, change_channel, hard_reset, remove_fabric)."

changedInput schema / properties / params / description

Previous value: -"Action-specific parameters (e.g. code, pin, channel, property, value). An unknown action returns that radio's supported action list with one-line summaries."New value: +"Action-specific parameters (e.g. code, pin, channel, property, value)."

First observedv7.14.2Jul 29, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations: long-running actions return immediately with long_running=true and complete out-of-band, S2 interactive pairing is not scriptable, admin access is required for parameter reads, and destructive actions are enumerated. It also clarifies that config-param reads neither create nor enable entities, resolving the mixed read/write nature of a tool whose annotations mark it destructive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, then alternatives, then caveats — a sensible ordering. The final Claude Desktop timeout/manual-approve paragraph is operationally useful but verbose and client-specific, diluting an otherwise tight description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need no explanation; the description instead supplies the behavioral context an agent needs (long-running semantics, auth, action-discovery fallback, destructive-action confirmation). Complete for a broad multi-action tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it distinguishes 'get_config_params' (cached list) from 'get_config_param' (cache or explicitly from device), explaining the refresh/scope behavior behind the params. It does not enumerate every action-specific param, but the schema plus the unknown-action-returns-list convention covers that.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Manage Home Assistant radios') and enumerates the four radio types it covers. It explicitly routes diagnostics to sibling tools ha_get_device / ha_get_system_health, so an agent can distinguish this tool from related readers without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use-this vs alternatives ('For node diagnostics and network summaries prefer ha_get_device / ha_get_system_health'), and calls out the non-scriptable case (interactive S2 PIN inclusion) with a redirect to SmartStart/QR or the HA UI. Prerequisite (HA administrator access) is stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server