Get System Health (incl. ZHA/Z-Wave/integration diagnostics)

Get Home Assistant system health, including Zigbee (ZHA), Z-Wave JS, and per-integration diagnostics dumps.

Returns health check results from integrations, system resources, and connectivity. Available information varies by installation type and loaded integrations.

The result also carries an ha_mcp_update object — {current, latest, update_available} — reporting whether a newer ha-mcp release is available (from PyPI for pip/Docker, or the Supervisor add-on store for the add-on), so you can proactively tell the user to upgrade. Present on every install type including the HA add-on (so a user who missed the Supervisor's update prompt still hears about it); omitted only for the unknown version and when HA_MCP_DISABLE_UPDATE_CHECK is set.

Parameters:

• include: Optional comma-separated list of additional data to include.

  • "repairs": Repair items from Settings > System > Repairs (active only by default; pass include_dismissed_repairs=True for all). To dismiss/ignore a repair, call ha_call_service(ws_command="repairs/ignore_issue", data={"domain": <domain>, "issue_id": <issue_id>, "ignore": true}).

  • "zha_network": ZHA Zigbee devices with radio signal summary (name, LQI, RSSI)

  • "zha_network_full": ZHA Zigbee devices with all device details (can be large on 100+ device networks; prefer "zha_network" for summary)

  • "zwave_network": Z-Wave JS network status and node summary (status, security, routing)

  • "thread_network": Thread/OpenThread Border Router (OTBR) summary — per border-router channel, extended_pan_id, and border_agent_id (integration-presence + radio-network view, not per-node Thread health)

  • "matter_network": Matter integration presence summary — config_entry_id, state, and title (per-node health is exposed separately via Matter node diagnostics, not here)

  • "themes": Installed theme names and defaults (sorted list of theme names, count, default_theme, default_dark_theme)

  • "diagnostics": Per-integration diagnostics dump — integration-defined JSON (commonly includes redacted config, device list, state snapshots; exact top-level keys vary by integration). REQUIRES config_entry_id. The canonical artifact users grab via Settings → Devices & Services → [integration] → ⋯ → Download diagnostics. Use this when triaging integration bugs or filing ha_report_issue for a specific integration. Payloads can be large (Hue ~290 KB, ZHA/MQTT/ESPHome several MB) — pair with diagnostics_fields or diagnostics_truncate_at_bytes to fit the LLM context budget.

  • "config_check": Validate HA configuration via POST /config/core/check_config (the pre-restart safety check; ha_restart runs it automatically). Returns {result: valid|invalid, is_valid, errors}; read-only/idempotent, takes no args.

  • "dead_entities": Surface orphaned/stale entity-registry entries by diffing the registry against the state machine and the live config-entries set. Returns confidence-tiered buckets — config_entry_orphans (owning integration instance gone; definitively dead) and stale_restored (HA restored the entity from the registry on startup but the loaded integration no longer provides it). Each item carries entity_id + platform so a client can propose cleanup with ha_remove_entity. Deliberately excludes unknown-state entities and merely-offline devices to keep false positives low. Read-only; takes no args.

  • Example: include="repairs,zha_network,zwave_network,config_check"

  • Example: include="diagnostics", config_entry_id="abc123..."

• include_dismissed_repairs: Include user-dismissed/ignored repairs (default: False). Only meaningful when "repairs" is in include.

• config_entry_id: Required when include contains diagnostics. The config entry ID of the integration (find via ha_get_integration).

• device_id: Optional. When set with include=diagnostics, returns the device-scoped diagnostics dump for that specific device under the integration (rather than the full integration dump). Some integrations only expose config-entry-level dumps; others expose both.

• diagnostics_fields: Optional list of top-level keys to keep from the diagnostics data payload (e.g. ["home_assistant", "issues"]). Accepts a JSON list or comma-separated string. Only applies with include=diagnostics.

• diagnostics_truncate_at_bytes: Optional byte cap on the serialized diagnostics payload (post-projection / post-data_path). On hit, drops data and emits truncated=true, bytes_total, byte_cap, plus available_fields (when the capped value is a dict). Only applies when include contains diagnostics. Recommended starting point: 20000 bytes.

• diagnostics_data_path: Optional dotted path into the diagnostics data sub-tree (e.g. "data.devices" for ZHA per-device records). Walks into the post-fields payload. Resolution failures replace data with null and surface data_path_error. Only applies when include contains diagnostics.

• diagnostics_data_offset / diagnostics_data_limit: Pagination on list-valued diagnostics_data_path results. When data_limit is set and the resolved path is a list, data becomes {"path", "items", "offset", "limit", "total", "has_more"}. Only applies when include contains diagnostics.

  Example workflow (walk a list-valued sub-tree one page at a time; the exact data_path varies by integration version): ha_get_system_health(include="diagnostics", config_entry_id="abc", diagnostics_data_path="<list-valued path>", diagnostics_data_limit=10) → inspect the page envelope's total / has_more → repeat with diagnostics_data_offset=10 for the next slice.