Home Assistant MCP Server

Official

by homeassistant-ai

Overview Schema Source Related Servers Discussions Admin

Python

Remote

Get System Overview

ha_get_overview

Read-onlyIdempotent

Get a categorized Home Assistant system overview: version, location, timezone, entity states, domain counts, and active notifications. Use minimal detail for common queries or request specific fields to reduce response size.

Instructions

Get AI-friendly system overview with intelligent categorization.

Returns comprehensive system information at the requested detail level, including Home Assistant base_url, version, location, timezone, entity overview, and active persistent notifications (if any). Use 'minimal' (default) for most queries. Domain counts and states_summary are always complete regardless of entity pagination. Standard/full modes paginate entities (default 200 per page) — use offset to fetch more. Use 'domains' filter to narrow scope.

Use fields= to project the response to only the keys you need — a significantly smaller payload when fetching a single sub-section (e.g. fields=["system_info"] returns just that section instead of the full overview). Requests composed only of system_info, notification, repair, or server metadata fields also skip the unrelated state, service, and registry reads.

Do not use this tool to inspect a known entity or a narrow set of entities. Use ha_get_state for one entity, ha_get_entity for registry metadata, or ha_search with a domain or area filter. An unprojected overview collects system-wide state, service, and registry data and can be expensive on large Home Assistant installations.

When (and only when) the ha-mcp settings-UI sidecar is running (stdio mode, e.g. Claude Desktop / Claude Code), the response includes a settings_url field — the local URL to the tool-configuration page. Hand this URL to the user when they ask how to enable or disable tools or change server settings. settings_url is emitted regardless of fields= projection (so it stays discoverable even when callers minimize the response) but only when the sidecar URL file actually exists.

In standalone HTTP / Docker modes, when an HTTP settings prefix is advertised, there is no sidecar URL file and the server can't know its externally reachable host. The response instead carries a settings_url_hint string telling the user where the page is mounted and how to find or construct the full URL. Hand whichever of the two fields is present to the user.

The response also carries an ha_mcp_update object {current, latest, update_available} reporting whether a newer ha-mcp release is available (PyPI for pip/Docker, the Supervisor add-on store for the add-on) — proactively tell the user when update_available is true. Emitted regardless of fields=; omitted only for the unknown version and when HA_MCP_DISABLE_UPDATE_CHECK is set.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`limit`	No	Max total entities across all domains (default: unlimited for minimal, 200 for standard/full). Counts and states always complete. Use with offset for pagination.
`fields`	No	Return only the specified top-level response keys to reduce response size (e.g. ["system_info", "domain_stats"]). None = full response (default). Available keys: success, system_summary, domain_stats, area_analysis, ai_insights, pagination, partial, warnings, device_types, service_availability, system_info, notification_count, notifications, repair_count, dismissed_repair_count, repairs, repairs_error, tool_discovery, settings_url, settings_url_hint, read_only_mode, read_only_mode_hint, ha_mcp_update. Note: ``settings_url`` (stdio mode), ``settings_url_hint`` (standalone HTTP/Docker mode), the ``read_only_mode`` / ``read_only_mode_hint`` pair (only while Read Only Mode is on), and ``ha_mcp_update`` (when an update check applies) are emitted regardless of ``fields=`` projection so the settings page, the active mode, and a newer ha-mcp release stay discoverable; see the tool description.
`offset`	No	Number of entities to skip for pagination (default: 0)
`domains`	No	Filter to specific domains (e.g. 'light,sensor' or ['light','sensor']). None = all domains. Useful to avoid context window overload.
`detail_level`	No	'minimal': 10 entities/domain, top-5 states (default); 'standard': 200 entities/page, top-10 states (use offset for more); 'full': 200 entities/page + entity_id + state + full states. Use 'domains', 'limit', or max_entities_per_domain to control size	minimal
`include_state`	No	Include state field for entities (None = auto based on level). Full defaults to True.
`include_entity_id`	No	Include entity_id field for entities (None = auto based on level). Full defaults to True.
`include_notifications`	No	Include active persistent notifications (default: True). Set False to skip.
`max_entities_per_domain`	No	Override default entity cap per domain (minimal=10, standard/full=unlimited). 0 = no limit on entities or states.
`include_dismissed_repairs`	No	Include user-dismissed/ignored repairs (default: False). Matches the HA Repairs UI which hides dismissed items by default. To dismiss/ignore a repair, call ha_call_service with ws_command="repairs/ignore_issue" and data={"domain": ..., "issue_id": ..., "ignore": true}.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv8.5.0Sep 16, 2026

changedInput schema / properties / fields / description

Previous value: -"Return only the specified top-level response keys to reduce response size (e.g. [\"system_info\", \"domains\"]). None = full response (default). Available keys: success, system_summary, domain_stats, area_analysis, ai_insights, pagination, partial, warnings, device_types, service_availability, system_info, notification_count, notifications, repair_count, dismissed_repair_count, repairs, repairs_error, tool_discovery, settings_url, settings_url_hint, read_only_mode, read_only_mode_hint, ha_mcp_update. Note: ``settings_url`` (stdio mode), ``settings_url_hint`` (standalone HTTP/Docker mode), the ``read_only_mode`` / ``read_only_mode_hint`` pair (only while Read Only Mode is on), and ``ha_mcp_update`` (when an update check applies) are emitted regardless of ``fields=`` projection so the settings page, the active mode, and a newer ha-mcp release stay discoverable; see the tool description."New value: +"Return only the specified top-level response keys to reduce response size (e.g. [\"system_info\", \"domain_stats\"]). None = full response (default). Available keys: success, system_summary, domain_stats, area_analysis, ai_insights, pagination, partial, warnings, device_types, service_availability, system_info, notification_count, notifications, repair_count, dismissed_repair_count, repairs, repairs_error, tool_discovery, settings_url, settings_url_hint, read_only_mode, read_only_mode_hint, ha_mcp_update. Note: ``settings_url`` (stdio mode), ``settings_url_hint`` (standalone HTTP/Docker mode), the ``read_only_mode`` / ``read_only_mode_hint`` pair (only while Read Only Mode is on), and ``ha_mcp_update`` (when an update check applies) are emitted regardless of ``fields=`` projection so the settings page, the active mode, and a newer ha-mcp release stay discoverable; see the tool description."

Changed1 schema field changedv8.4.1Sep 2, 2026

changedInput schema / properties / fields / description

Previous value: -"Return only the specified top-level response keys to reduce response size (e.g. [\"system_info\", \"domains\"]). None = full response (default). Available keys: success, system_summary, domain_stats, area_analysis, ai_insights, pagination, partial, warnings, device_types, service_availability, system_info, notification_count, notifications, repair_count, dismissed_repair_count, repairs, repairs_error, tool_discovery, settings_url, settings_url_hint, read_only_mode, read_only_mode_hint, ha_mcp_update. Note: ``settings_url`` (stdio mode), ``settings_url_hint`` (HTTP/Docker/OAuth mode), the ``read_only_mode`` / ``read_only_mode_hint`` pair (only while Read Only Mode is on), and ``ha_mcp_update`` (when an update check applies) are emitted regardless of ``fields=`` projection so the settings page, the active mode, and a newer ha-mcp release stay discoverable; see the tool description."New value: +"Return only the specified top-level response keys to reduce response size (e.g. [\"system_info\", \"domains\"]). None = full response (default). Available keys: success, system_summary, domain_stats, area_analysis, ai_insights, pagination, partial, warnings, device_types, service_availability, system_info, notification_count, notifications, repair_count, dismissed_repair_count, repairs, repairs_error, tool_discovery, settings_url, settings_url_hint, read_only_mode, read_only_mode_hint, ha_mcp_update. Note: ``settings_url`` (stdio mode), ``settings_url_hint`` (standalone HTTP/Docker mode), the ``read_only_mode`` / ``read_only_mode_hint`` pair (only while Read Only Mode is on), and ``ha_mcp_update`` (when an update check applies) are emitted regardless of ``fields=`` projection so the settings page, the active mode, and a newer ha-mcp release stay discoverable; see the tool description."

First observedv7.14.2Jul 29, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations cover readOnlyHint, openWorldHint, and idempotentHint, but the description adds substantial behavior beyond them: pagination semantics (200/page in standard/full), the guarantee that counts/states_summary stay complete despite pagination, the mode-dependent settings_url vs settings_url_hint behavior, the always-emitted fields regardless of fields= projection, and the ha_mcp_update object with its conditional omission. This is rich behavioral disclosure that the annotations alone would not convey. No contradiction with annotations.

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

Conciseness3/5

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

The description is well-structured and front-loaded with purpose and usage guidance, but it is genuinely long (roughly 450+ words). The settings_url/settings_url_hint/hint-handling paragraphs and the ha_mcp_update explanation are verbose, with some redundancy against the schema's own fields= note about always-emitted keys. Well-organized but over-written for what could be tightened.

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

Completeness4/5

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

For a high-complexity tool (10 params, 0 required, three detail modes, pagination, conditional fields, mode-dependent behavior) with an output schema and rich annotations, the description is nearly complete: it covers return contents, mode differences, pagination, when not to use it, alternatives, projection semantics, and conditional update/settings fields. Minor gaps remain around exact error behavior, but nothing an agent needs to invoke it correctly is missing. The output schema covers return-value structure, so the description need not.

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. The description adds meaningful semantics beyond the schema: it explains how detail_level interacts with pagination and entity caps, how fields= can skip unrelated state/service/registry reads for certain key combinations, and that settings_url/settings_url_hint/ha_mcp_update are emitted regardless of projection. This goes beyond what the schema's per-parameter descriptions state, so a 4 is warranted.

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?

The description opens with a specific verb+resource ('Get AI-friendly system overview') and enumerates the concrete contents (base_url, version, location, timezone, entity overview, notifications). It distinguishes itself from siblings by explicitly naming ha_get_state, ha_get_entity, and ha_search as the correct tools for narrow entity inspection. This differentiates it clearly from the many ha_get_* siblings.

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?

Provides explicit when-to-use guidance ('Use 'minimal' (default) for most queries'), explicit when-not-to-use ('Do not use this tool to inspect a known entity or a narrow set of entities'), and names the exact alternatives (ha_get_state, ha_get_entity, ha_search). It also flags cost/performance considerations for large installations, giving the agent a decision rule based on scope.

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

Deploy Server