Home Assistant MCP Server

Official

by homeassistant-ai

Overview Schema Source Related Servers Discussions Admin

Python

Remote

List Helpers

ha_config_list_helpers

Read-onlyIdempotent

List Home Assistant helpers by type with their configurations. Use the describe option to view required fields before creating or updating a helper.

Instructions

List Home Assistant helpers of a specific type with their configurations.

Returns one page of helpers; total_count and has_more report the full set. Each record carries the configuration for its helper: id (immutable storage key), entity_id (current — address the helper by this, where available), name (current display name), original_name (creation-time name), icon, type-specific settings, and area and label assignments. A flow helper record carries entry_id and options instead of id; a custom helper integration's options are withheld, marked options_withheld.

For a helper renamed in the UI, id/original_name keep the storage values while entity_id/name reflect the current entity registry (entity_id is the identifier ha_config_set_helper resolves against, so prefer it over id for a renamed helper). entity_id/original_name are present only for storage-collection helpers matched in the entity registry — types with no backing entity (e.g. tag), and every record when the registry read degrades, carry only id/name (a warning flags the degraded case).

Storage types list what HA's {type}/list command returns: the storage-backed helpers (created via UI/API), not the YAML-defined ones. person is the exception — HA lists its YAML-configured persons alongside the storage ones, so both appear here.

Listing flow types requires the ha_mcp_tools custom component (>= 1.1.0); without it, such a listing returns a COMPONENT_NOT_INSTALLED error.

With helper_type="all", each record carries its own helper_type. This mode is component-only (there is no single built-in command that lists all types): without the ha_mcp_tools component it returns a COMPONENT_NOT_INSTALLED error rather than a partial or empty list.

describe=True returns each field's name, type, required flag, options, default and (with helper_id) current value, or the menu_options a menu-based helper needs a menu_choice from. Call it before ha_config_set_helper to learn the config keys for a type.

EXAMPLES:

List all counters: ha_config_list_helpers("counter")
List every helper type at once: ha_config_list_helpers("all")
Next page: ha_config_list_helpers("input_boolean", offset=100)
Fields for a template sensor: ha_config_list_helpers("template", describe=True, menu_choice="sensor")

For detailed helper documentation, use ha_get_skill_guide.

list all helpers input_boolean input_number input_text counter timer input_datetime input_select

Input Schema

TableJSON Schema

Name	Required	Description
`limit`	No	Max helpers to return per page
`offset`	No	Number of helpers to skip for pagination
`describe`	No	Instead of listing, return the fields ha_config_set_helper accepts in config for helper_type, as Home Assistant reports them (the form the HA UI shows).
`helper_id`	No	describe only: an existing helper (config entry id for flow helpers, entity_id or id otherwise); each field then carries its current value.
`helper_type`	Yes	Helper type to list: a storage type (input_boolean, counter, timer, ...), a helper flow Home Assistant lists (template, group, utility_meter, ...), or 'all' for every type in one call.
`menu_choice`	No	describe only: sub-type of a menu-based helper (template, group), e.g. 'sensor'.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv8.7.0Oct 15, 2026

addedInput schema / properties / describe

Added value: +{
+  "default": false,
+  "description": "Instead of listing, return the fields ha_config_set_helper accepts in config for helper_type, as Home Assistant reports them (the form the HA UI shows).",
+  "type": "boolean"
+}

addedInput schema / properties / helper_id

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "describe only: an existing helper (config entry id for flow helpers, entity_id or id otherwise); each field then carries its current value."
+}

changedInput schema / properties / helper_type / anyOf

Previous value: -[
-  {
-    "enum": [
-      "input_button",
-      "input_boolean",
-      "input_select",
-      "input_number",
-      "input_text",
-      "input_datetime",
-      "counter",
-      "timer",
-      "schedule",
-      "zone",
-      "person",
-      "tag",
-      "all"
-    ],
-    "type": "string"
-  },
-  {
-    "enum": [
-      "template",
-      "group",
-      "utility_meter",
-      "derivative",
-      "min_max",
-      "threshold",
-      "integration",
-      "statistics",
-      "trend",
-      "random",
-      "filter",
-      "tod",
-      "generic_thermostat",
-      "switch_as_x",
-      "generic_hygrostat",
-      "history_stats",
-      "mold_indicator"
-    ],
-    "type": "string"
-  }
-]New value: +[
+  {
+    "enum": [
+      "input_button",
+      "input_boolean",
+      "input_select",
+      "input_number",
+      "input_text",
+      "input_datetime",
+      "counter",
+      "timer",
+      "schedule",
+      "zone",
+      "person",
+      "tag"
+    ],
+    "type": "string"
+  },
+  {
+    "const": "all",
+    "type": "string"
+  },
+  {
+    "type": "string"
+  }
+]

changedInput schema / properties / helper_type / description

Previous value: -"Helper type to list. Storage types are listed on all installs; flow-based types require the ha_mcp_tools custom component. Pass 'all' to list every helper type in one call (also requires the ha_mcp_tools component)."New value: +"Helper type to list: a storage type (input_boolean, counter, timer, ...), a helper flow Home Assistant lists (template, group, utility_meter, ...), or 'all' for every type in one call."

addedInput schema / properties / menu_choice

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "describe only: sub-type of a menu-based helper (template, group), e.g. 'sensor'."
+}

Changed2 schema fields changedv8.6.0Oct 1, 2026

changedInput schema / properties / limit / description

Previous value: -"Max helpers to return per page (default: 100)"New value: +"Max helpers to return per page"

changedInput schema / properties / offset / description

Previous value: -"Number of helpers to skip for pagination (default: 0)"New value: +"Number of helpers to skip for pagination"

Changed1 schema field changedv8.3.0Aug 19, 2026

changedInput schema / properties / helper_type / anyOf

Previous value: -[
-  {
-    "enum": [
-      "input_button",
-      "input_boolean",
-      "input_select",
-      "input_number",
-      "input_text",
-      "input_datetime",
-      "counter",
-      "timer",
-      "schedule",
-      "zone",
-      "person",
-      "tag",
-      "all"
-    ],
-    "type": "string"
-  },
-  {
-    "enum": [
-      "template",
-      "group",
-      "utility_meter",
-      "derivative",
-      "min_max",
-      "threshold",
-      "integration",
-      "statistics",
-      "trend",
-      "random",
-      "filter",
-      "tod",
-      "generic_thermostat",
-      "switch_as_x",
-      "generic_hygrostat"
-    ],
-    "type": "string"
-  }
-]New value: +[
+  {
+    "enum": [
+      "input_button",
+      "input_boolean",
+      "input_select",
+      "input_number",
+      "input_text",
+      "input_datetime",
+      "counter",
+      "timer",
+      "schedule",
+      "zone",
+      "person",
+      "tag",
+      "all"
+    ],
+    "type": "string"
+  },
+  {
+    "enum": [
+      "template",
+      "group",
+      "utility_meter",
+      "derivative",
+      "min_max",
+      "threshold",
+      "integration",
+      "statistics",
+      "trend",
+      "random",
+      "filter",
+      "tod",
+      "generic_thermostat",
+      "switch_as_x",
+      "generic_hygrostat",
+      "history_stats",
+      "mold_indicator"
+    ],
+    "type": "string"
+  }
+]

First observedv7.14.2Jul 29, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial behavioral context: pagination via total_count/has_more, the COMPONENT_NOT_INSTALLED error conditions, degraded-registry warnings, withheld options, and the person YAML exception.

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?

Content is front-loaded and the examples section is useful, but the description is over-long with redundancy (COMPONENT_NOT_INSTALLED stated twice) and ends with an awkward keyword-stuffed tail ('list all helpers input_boolean input_number ...') that does not earn its place.

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?

Given six parameters, an output schema, and the type/degradation edge cases, the description covers what an agent needs: record fields, pagination, error modes, and the describe workflow. Nothing essential is missing.

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 beyond the schema: helper_type='all' is component-only and errors rather than returning partial results, and describe/helper_id/menu_choice are tied to the set_helper workflow.

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 opening sentence states a specific verb+resource with scope: 'List Home Assistant helpers of a specific type with their configurations.' It is unambiguous versus write siblings like ha_config_set_helper and is clearly a list/read tool.

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

Usage Guidelines4/5

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

It gives explicit context ('Call it before ha_config_set_helper to learn the config keys for a type') and routes to ha_get_skill_guide for deeper docs. It does not, however, state when NOT to use it or contrast it against near-neighbors like ha_config_list_groups.

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

Deploy Server