Home Assistant MCP

Instructions

Args:
    entity_id: The Home Assistant entity ID to control (format: domain.entity)
    state: The desired state ('on' or 'off')

Implementation Reference

• app/tools/device_controls.py:21-50 (handler)

  The async handler function implementing the control_device tool. It validates inputs, calls the Home Assistant API to turn entities on/off, and returns success/error messages.

  async def control_device(entity_id: str, state: str) -> str:
      """Control a Home Assistant entity by turning it on or off.
      
      Args:
          entity_id: The Home Assistant entity ID to control (format: domain.entity)
          state: The desired state ('on' or 'off')
      """
      # Basic validation
      if not entity_id or "." not in entity_id:
          return f"Invalid entity ID format: {entity_id}. Must be in format: domain.entity"
      
      state = state.lower()
      if state not in ["on", "off"]:
          return f"Invalid state: {state}. Must be 'on' or 'off'"
      
      # Check token
      if not HOME_ASSISTANT_TOKEN:
          return "Home Assistant token not configured. Set HOME_ASSISTANT_TOKEN environment variable."
      
      # Get domain from entity_id
      domain = entity_id.split(".")[0]
      service = "turn_on" if state == "on" else "turn_off"
      
      # Call the HA API
      result = await make_ha_request(domain, service, entity_id)
      
      if result["success"]:
          return f"Successfully turned {state} {entity_id}"
      else:
          return f"Failed to control {entity_id}: {result.get('error', 'Unknown error')}"

• app/tools/device_controls.py:17-17 (registration)

  The registration of the control_device tool using the FastMCP tool decorator within the init_tools function.

  fastmcp_instance.tool()(control_device)