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

Removes a Home Assistant helper or integration config entry by helper ID, entity ID, or entry ID. Routes to the correct backend deletion path and returns clear errors if the target is missing.

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 with four routing paths driven by helper_type.

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.

SUPPORTED HELPER TYPES:

  • SIMPLE (12, websocket-delete): input_button, input_boolean, input_select, input_number, input_text, input_datetime, counter, timer, schedule, zone, person, tag.

  • FLOW (17, config-entry-delete via entity lookup): 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.

ROUTING:

  • SIMPLE helper_type + bare helper_id or entity_id → websocket delete.

  • FLOW helper_type + 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.

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

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

MISSING-TARGET CONTRACT: A target that is confirmed absent raises a structured error rather than returning silent success, so a typo'd or stale identifier surfaces immediately at the caller layer (the success boolean is what agent wrappers branch on). The error code per-path follows the target shape:

  • SIMPLE (bare helper_id or entity_id): state-machine empty AND entity registry empty → raises ENTITY_NOT_FOUND.

  • FLOW (entity_id): not in entity registry → raises ENTITY_NOT_FOUND. YAML-configured helpers (no config entry backing) raise RESOURCE_NOT_FOUND. A bare helper_id (no .) on a FLOW target raises ENTITY_NOT_FOUND — FLOW resolution needs a full entity_id. TOCTOU 404 on the resolved entry_id raises RESOURCE_NOT_FOUND.

  • Direct config entry (helper_type=None): backend returns HTTP 404 → raises RESOURCE_NOT_FOUND.

  • Config subentry: backend returns a "not_found" error → raises RESOURCE_NOT_FOUND.

Idempotency at the contract level still holds (call N times = same response). Transient connectivity failures (WebSocket disconnected, network timeouts) 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 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. Recovery requires a usable backup and supported restore path.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
waitNoWait for entity removal. Default: True. Ignored when helper_type=None or helper_type='config_subentry' (no entity poll, require_restart returned).
targetYesWhat 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).
confirmNoMust be True to confirm removal.
helper_typeNoHelper 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.
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. 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"
+  }
+]
  2. 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 declare destructiveHint=true and idempotentHint=true, and the description adds substantial behavioral context: the missing-target contract with specific error codes per path, the TOCTOU 404 behavior, the fact that FLOW removal removes all sub-entities, and the warning about referenced helpers/integrations failing. It also clarifies idempotency at the contract level despite destructive semantics.

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?

The description is long but every section earns its place: routing, error contract, examples, and warning are all necessary for correct invocation of a complex multi-path tool. It is well-structured with clear headers and front-loaded purpose. Slightly verbose in the error contract section, but that detail is operationally important.

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 tool with 5 parameters and an output schema, the description covers routing, error codes, idempotency, connectivity failures, examples, and safety warnings. The output schema exists, so return values need not be described. Nothing an agent needs to call this correctly 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 description coverage is 100%, so the schema already documents all five parameters. The description adds value by explaining the routing logic that ties target/helper_type/subentry_id together, and by giving concrete examples of valid combinations. It doesn't add much per-parameter detail beyond the schema, but the routing section compensates for the interaction complexity.

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 states a specific verb ('Remove') and resource ('Home Assistant helper or integration config entry'), and explicitly unifies three backend removal mechanisms behind one entry point. It clearly distinguishes itself from sibling tools like ha_remove_entity and ha_remove_device by naming them and explaining the boundary.

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?

The 'WHEN NOT TO USE' section explicitly names ha_remove_entity for entity-only removal and explains YAML-configured helpers require editing YAML instead. The routing section further clarifies which target/helper_type combinations are valid, giving an agent concrete decision criteria.

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