Skip to main content
Glama
homeassistant-ai

Home Assistant MCP Server

Official
by homeassistant-ai
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Remove Helper or Integration

ha_remove_helpers_integrations
DestructiveIdempotent

Delete Home Assistant helpers, integration config entries, or config subentries by helper ID, entity ID, or entry ID; resolves the correct backend removal path.

Instructions

Remove a Home Assistant helper or integration config entry.

Unifies three backend removal mechanisms — simple-helper websocket delete, config-entry delete, and config-subentry delete — behind one entry point; helper_type picks the path, or the entity registry does when an entity_id comes without one.

WHEN NOT TO USE:

  • Removing only an entity (without deleting its underlying helper or config entry) — use ha_remove_entity instead.

  • YAML-configured helpers — they have no storage backend. Edit the YAML file and reload the relevant integration.

ROUTING:

  • SIMPLE helper_type (input_button, input_boolean, input_select, input_number, input_text, input_datetime, counter, timer, schedule, zone, person, tag) + bare helper_id or entity_id → websocket delete.

  • FLOW helper_type (any helper flow Home Assistant lists: template, group, utility_meter, derivative, ...; custom helper integrations too)

    • full entity_id → resolve entity_id to config_entry_id via entity_registry, then delete the config entry. All sub-entities (e.g. utility_meter tariffs) are removed together. An entity registered by another integration is refused with VALIDATION_INVALID_PARAMETER and nothing is deleted.

  • helper_type=None + entity_id → the entity's registry entry names its helper (storage type or helper flow); an entity of any other integration is refused with VALIDATION_INVALID_PARAMETER.

  • helper_type=None + entry_id → direct config entry delete (any integration).

  • helper_type="config_subentry" + parent entry_id + subentry_id → delete one config subentry.

A target that cannot be removed raises a structured error rather than returning silent success: ENTITY_NOT_FOUND when the entity_id is absent from both the state machine and the entity registry (a bare helper_id on a FLOW target also raises it — FLOW resolution needs a full entity_id); RESOURCE_NOT_FOUND when it exists but is not storage- or registry-managed (a YAML-configured helper, or an entity with a state but no registry entry), for a config entry the backend reports as 404, or for a missing config subentry. Calling N times gives the same response. Transient connectivity failures raise their own codes (WEBSOCKET_DISCONNECTED, CONNECTION_FAILED) so retry logic can branch separately.

EXAMPLES:

  • Remove SIMPLE button: ha_remove_helpers_integrations(target="my_button", helper_type="input_button", confirm=True)

  • Remove FLOW utility_meter (any sub-entity works): ha_remove_helpers_integrations(target="sensor.energy_peak", helper_type="utility_meter", confirm=True)

  • Remove whatever helper owns an entity: ha_remove_helpers_integrations(target="sensor.energy_peak", confirm=True)

  • Remove any integration by entry_id: ha_remove_helpers_integrations(target="01HXYZ...", confirm=True)

  • Remove a config subentry: ha_remove_helpers_integrations(target="01HXYZ...", helper_type="config_subentry", subentry_id="subentry-123", confirm=True)

WARNING: Removing a helper or integration that is referenced by automations, scripts, or other integrations may cause those to fail. Use ha_search() / ha_get_integration() to verify before removal. ha_manage_backup(scope="edits", action="restore") recreates removed FLOW helpers whose options could be snapshotted, and config subentries. It cannot recreate custom helper integrations (their options are withheld) or otp (no stored options); re-add those yourself, otp through the user in the HA UI.

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

TableJSON Schema
NameRequiredDescriptionDefault
waitNoWait for entity removal. Default: True. Ignored for a direct config entry delete (an entry_id target) or helper_type='config_subentry' (no entity poll, require_restart returned).
targetYesWhat to remove. One of: (a) bare helper_id for SIMPLE helpers, e.g. 'my_button'; (b) full entity_id, e.g. 'input_button.my_button' or 'sensor.my_meter'; (c) config entry_id for any integration, with helper_type omitted, e.g. value from ha_get_integration(); (d) parent config entry_id for a config subentry.
confirmNoMust be True to confirm removal.
helper_typeNoHelper type of target; ROUTING says which value takes which removal path.
subentry_idNoConfig subentry ID to remove when helper_type='config_subentry'.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv8.7.0
    • 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",
-      "config_subentry",
-      "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"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "enum": [
+      "input_button",
+      "input_boolean",
+      "input_select",
+      "input_number",
+      "input_text",
+      "input_datetime",
+      "counter",
+      "timer",
+      "schedule",
+      "zone",
+      "person",
+      "tag"
+    ],
+    "type": "string"
+  },
+  {
+    "const": "config_subentry",
+    "type": "string"
+  },
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
    • changedInput schema / properties / helper_type / description
      Previous value: -"Helper type. Required when target is a helper_id (bare) or entity_id. Set to None when target is a config entry_id to remove any integration. Use 'config_subentry' to remove a config subentry under target."New value: +"Helper type of target; ROUTING says which value takes which removal path."
    • changedInput schema / properties / target / description
      Previous value: -"What to remove. One of: (a) bare helper_id for SIMPLE helpers, e.g. 'my_button'; (b) full entity_id, e.g. 'input_button.my_button' or 'sensor.my_meter'; (c) config entry_id for any integration, e.g. value from ha_get_integration(); (d) parent config entry_id for a config subentry."New value: +"What to remove. One of: (a) bare helper_id for SIMPLE helpers, e.g. 'my_button'; (b) full entity_id, e.g. 'input_button.my_button' or 'sensor.my_meter'; (c) config entry_id for any integration, with helper_type omitted, e.g. value from ha_get_integration(); (d) parent config entry_id for a config subentry."
    • changedInput schema / properties / wait / description
      Previous value: -"Wait for entity removal. Default: True. Ignored when helper_type=None or helper_type='config_subentry' (no entity poll, require_restart returned)."New value: +"Wait for entity removal. Default: True. Ignored for a direct config entry delete (an entry_id target) or helper_type='config_subentry' (no entity poll, require_restart returned)."
  2. Changed1 schema field changedv8.6.0
    • changedInput schema / properties / target / description
      Previous value: -"What to remove. One of: (a) bare helper_id for SIMPLE helpers (requires helper_type), e.g. 'my_button'; (b) full entity_id (requires helper_type), e.g. 'input_button.my_button' or 'sensor.my_meter'; (c) config entry_id for any integration (helper_type=None), e.g. value from ha_get_integration(); (d) parent config entry_id for config_subentry (requires helper_type='config_subentry' and subentry_id)."New value: +"What to remove. One of: (a) bare helper_id for SIMPLE helpers, e.g. 'my_button'; (b) full entity_id, e.g. 'input_button.my_button' or 'sensor.my_meter'; (c) config entry_id for any integration, e.g. value from ha_get_integration(); (d) parent config entry_id for a config subentry."
  3. Changed1 schema field changedv8.3.0
    • 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",
-      "config_subentry",
-      "template",
-      "group",
-      "utility_meter",
-      "derivative",
-      "min_max",
-      "threshold",
-      "integration",
-      "statistics",
-      "trend",
-      "random",
-      "filter",
-      "tod",
-      "generic_thermostat",
-      "switch_as_x",
-      "generic_hygrostat"
-    ],
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "enum": [
+      "input_button",
+      "input_boolean",
+      "input_select",
+      "input_number",
+      "input_text",
+      "input_datetime",
+      "counter",
+      "timer",
+      "schedule",
+      "zone",
+      "person",
+      "tag",
+      "config_subentry",
+      "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"
+  },
+  {
+    "type": "null"
+  }
+]
  4. First observedv7.14.2

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare destructive/idempotent, but the description goes far beyond them: it discloses cascade behavior (sub-entities removed together), structured error codes per failure mode, retry-branchable transient codes, and backup/restore limitations via `ha_manage_backup`. The idempotency claim ('Calling N times gives the same response') and the refusal path (VALIDATION_INVALID_PARAMETER, nothing deleted) are exactly the kind of detail annotations cannot carry.

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 cleanly sectioned into WHEN NOT TO USE, ROUTING, errors, examples, and warnings. It is long, and the closing Claude Desktop timeout workaround is tangential, but nearly every line carries actionable routing or failure semantics.

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?

For a destructive, multi-path removal tool with five parameters and an output schema, the description supplies routing, failure codes, cascade effects, and recovery guidance. Nothing material for correct invocation is missing, and return-value details are correctly delegated to the output schema.

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 earns above baseline by explaining what each parameter value *routes to* — helper_type selects websocket vs config-entry vs subentry deletion, entity_id resolution goes through the entity registry, and the confirm flag's blocking role is shown in every example.

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 and resource ('Remove a Home Assistant helper or integration config entry') and immediately differentiates itself from the closest sibling by naming `ha_remove_entity`. The routing section makes clear it unifies three distinct backend removal mechanisms, so an agent understands the tool's scope precisely.

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?

An explicit WHEN NOT TO USE section names two exclusions (entity-only removal, YAML-configured helpers) and routes each to the correct alternative, including `ha_remove_entity` and direct YAML editing. The ROUTING block gives deterministic when-to-use rules keyed off helper_type/entity_id/entry_id combinations.

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

Deploy Server

Other Tools