Add ha_remove_entity tool (config/entity_registry/remove)

[Patch76]

What problem does this solve?

When a helper or device is deleted, core.entity_registry sometimes retains a stale entry. There is currently no ha-mcp tool to remove an individual entity registry entry.

Why not existing tools?

• ha_config_remove_helper: removes the helper config entry, does not target the entity registry directly
• ha_remove_device: targets devices, not individual entity entries
• ha_set_entity(enabled=False): hides the entity, does not remove the registry entry

The API path

HA Core WebSocket:

type: config/entity_registry/remove
entity_id: <entity_id>

Implementation: registry.async_remove(entity_id) — no platform check, works for orphaned entries as long as entity_id exists in the registry.

Proposed tool

ha_remove_entity(entity_id: str)

• Sends config/entity_registry/remove via WebSocket
• Returns error if entity not found
• No HA restart required

Context

Came up in homeassistant-ai/skills#39, where direct .storage/ manipulation was proposed as a workaround. The right fix is a proper tool.

[github-actions]

The ha_remove_entity tool does not exist in ha-mcp. Currently, users can only remove entire devices with ha_remove_device or specific helper entities with ha_config_remove_helper. While ha_set_entity(enabled=False) can be used to hide or disable an entity, it does not remove the stale entry from the Home Assistant entity registry.

Adding this tool will provide a direct way to clean up orphaned or stale entity entries using the Home Assistant config/entity_registry/remove WebSocket API.

🔍 Analysis

The ha_remove_entity tool does not exist in ha-mcp.

This feature request addresses a gap in entity management where stale entries in the core.entity_registry cannot be easily removed via existing tools. While ha_remove_device handles device-level cleanup and ha_config_remove_helper handles specific helper types, there is no generic tool for individual entity registry removal.

The proposed tool will implement the config/entity_registry/remove WebSocket command, which is the backend equivalent of deleting an entity via the Home Assistant UI. This is particularly useful for cleaning up "orphaned" entities left behind after a device or integration has been partially removed.

🛠️ Suggested Steps

1. Add the ha_remove_entity tool to src/ha_mcp/tools/tools_entities.py within the register_entity_tools function.
2. Implement the tool using the config/entity_registry/remove WebSocket message type.
3. Include proper error handling for cases where the entity is not found or the removal fails (e.g., if the entity is currently active and managed by a running integration).
4. Verify the tool by attempting to remove a known stale entity ID.

📊 Technical Analysis (for maintainers)

Root Cause

The current toolset lacks a generic interface for the Home Assistant config/entity_registry/remove WebSocket API.

Affected Code

• src/ha_mcp/tools/tools_entities.py - This is the most appropriate location for the new tool, as it already houses ha_get_entity and ha_set_entity.

Proposed Fix

--- a/src/ha_mcp/tools/tools_entities.py
+++ b/src/ha_mcp/tools/tools_entities.py
@@ -1025,3 +1025,65 @@
                     context={
                         "entity_id": entity_id if isinstance(entity_id, str) else entity_ids
                     },
                 )
+
+    @mcp.tool(
+        tags={"Entity Registry"},
+        annotations={
+            "destructiveHint": True,
+            "idempotentHint": True,
+            "title": "Remove Entity"
+        }
+    )
+    @log_tool_usage
+    async def ha_remove_entity(
+        entity_id: Annotated[
+            str,
+            Field(description="Entity ID to remove from the registry (e.g., 'sensor.stale_entity')"),
+        ],
+    ) -> dict[str, Any]:
+        """
+        Remove an orphaned or stale entity from the Home Assistant entity registry.
+
+        WARNING: This removes the entity entry from the registry.
+        - Use only for orphaned entities that are no longer provided by any integration
+        - Active entities will typically be re-added by their integration upon restart or reload
+        - This does NOT remove the underlying device or config entry
+
+        EXAMPLES:
+        - Remove stale entity: ha_remove_entity("sensor.stale_temp")
+
+        NOTE: For most use cases, consider disabling or hiding the entity instead:
+        ha_set_entity(entity_id="sensor.temp", enabled=False)
+        ha_set_entity(entity_id="sensor.temp", hidden=True)
+        """
+        try:
+            # Send removal message to entity registry
+            message: dict[str, Any] = {
+                "type": "config/entity_registry/remove",
+                "entity_id": entity_id,
+            }
+
+            logger.info(f"Removing entity from registry: {entity_id}")
+            result = await client.send_websocket_message(message)
+
+            if not result.get("success"):
+                error = result.get("error", {})
+                error_msg = (
+                    error.get("message", str(error))
+                    if isinstance(error, dict)
+                    else str(error)
+                )
+                
+                # Check for specific error if entity doesn't exist
+                if "not found" in error_msg.lower():
+                    raise_tool_error(
+                        create_error_response(
+                            ErrorCode.ENTITY_NOT_FOUND,
+                            f"Entity '{entity_id}' not found in registry",
+                            context={"entity_id": entity_id},
+                            suggestions=[
+                                "Use ha_search_entities() to find valid entity IDs",
+                            ],
+                        )
+                    )
+
+                raise_tool_error(
+                    create_error_response(
+                        ErrorCode.SERVICE_CALL_FAILED,
+                        f"Failed to remove entity: {error_msg}",
+                        context={"entity_id": entity_id},
+                    )
+                )
+
+            return {
+                "success": True,
+                "entity_id": entity_id,
+                "message": f"Successfully removed entity '{entity_id}' from registry",
+            }
+
+        except ToolError:
+            raise
+        except Exception as e:
+            logger.error(f"Error removing entity: {e}")
+            exception_to_structured_error(
+                e,
+                context={"entity_id": entity_id},
+            )

Related Issues/PRs

No similar issues found in current session.

🤖 Automated analysis by Issue Bot

[kingpanther13]

Very good catch! I'm surprised this hasn't come up before.

Would you be interested in making the PR for closing this issue? It should be a fairly straight forward PR to make to close this issue. Since you've been doing so much with Claude code in the skills repo, I think you should be capable of doing it if you're interested.

[Patch76]

@kingpanther13 — thank you for the invitation and for triaging this issue! 🙏

I want to be upfront: I'm not a regular open-source contributor, and I'm honestly
not sure I've fully met the bar you'd expect here. I've done my best to:

• Follow CONTRIBUTING.md and AGENTS.md
• Model the implementation on ha_remove_device
• Cover the relevant code paths with tests

...but I'm aware there may be things I've missed or misjudged.
I'd genuinely appreciate your honest feedback — even if that means going back
to the drawing board on parts of it.

[github-actions]

✅ This issue has been addressed in the dev channel!

A fix for this issue has been merged to master (PR #876) and is available for testing in the dev channel.

Test the fix before the next stable release (biweekly Wednesday):
📖 Dev Channel Documentation

Quick start

# Run dev version
uvx ha-mcp-dev

# Check version
uvx ha-mcp-dev --version

Docker:

docker pull ghcr.io/homeassistant-ai/ha-mcp:dev
docker run --rm -i \
  -e HOMEASSISTANT_URL=http://your-ha:8123 \
  -e HOMEASSISTANT_TOKEN=your_token \
  ghcr.io/homeassistant-ai/ha-mcp:dev

---

After testing:

• ✅ If it's fixed: Great! Feel free to comment here to confirm
• ❌ If still broken: Open a new issue and reference Add ha_remove_entity tool (config/entity_registry/remove) #874
  • Closed issues can't be reopened by reporters
  • A new issue helps us track the problem properly