entity_action
Control Home Assistant entities by performing actions like on, off, or toggle. Specify the entity ID and optional parameters such as brightness or temperature to customize the operation. Integrate with Hass-MCP for direct smart home automation.
Instructions
Perform an action on a Home Assistant entity (on, off, toggle)
Args: entity_id: The entity ID to control (e.g. 'light.living_room') action: The action to perform ('on', 'off', 'toggle') params: Optional dictionary of additional parameters for the service call
Returns: The response from Home Assistant
Examples: entity_id="light.living_room", action="on", params={"brightness": 255} entity_id="switch.garden_lights", action="off" entity_id="climate.living_room", action="on", params={"temperature": 22.5}
Domain-Specific Parameters: - Lights: brightness (0-255), color_temp, rgb_color, transition, effect - Covers: position (0-100), tilt_position - Climate: temperature, target_temp_high, target_temp_low, hvac_mode - Media players: source, volume_level (0-1)
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | ||
| entity_id | Yes | ||
| params | No |
Implementation Reference
- app/server.py:87-126 (handler)The primary handler function for the 'entity_action' MCP tool. Registers the tool via @mcp.tool(), provides input schema via type hints and comprehensive docstring with examples and domain-specific parameters, validates actions, maps to HA services (turn_on/off/toggle), extracts domain from entity_id, merges params, logs the action, and delegates execution to the generic call_service helper.@mcp.tool() @async_handler("entity_action") async def entity_action(entity_id: str, action: str, params: Optional[Dict[str, Any]] = None) -> dict: """ Perform an action on a Home Assistant entity (on, off, toggle) Args: entity_id: The entity ID to control (e.g. 'light.living_room') action: The action to perform ('on', 'off', 'toggle') params: Optional dictionary of additional parameters for the service call Returns: The response from Home Assistant Examples: entity_id="light.living_room", action="on", params={"brightness": 255} entity_id="switch.garden_lights", action="off" entity_id="climate.living_room", action="on", params={"temperature": 22.5} Domain-Specific Parameters: - Lights: brightness (0-255), color_temp, rgb_color, transition, effect - Covers: position (0-100), tilt_position - Climate: temperature, target_temp_high, target_temp_low, hvac_mode - Media players: source, volume_level (0-1) """ if action not in ["on", "off", "toggle"]: return {"error": f"Invalid action: {action}. Valid actions are 'on', 'off', 'toggle'"} # Map action to service name service = action if action == "toggle" else f"turn_{action}" # Extract the domain from the entity_id domain = entity_id.split(".")[0] # Prepare service data data = {"entity_id": entity_id, **(params or {})} logger.info(f"Performing action '{action}' on entity: {entity_id} with params: {params}") return await call_service(domain, service, data)
- app/hass.py:312-331 (helper)Generic helper function used by entity_action to perform the actual Home Assistant service call via POST to /api/services/{domain}/{service}. Includes error handling decorator and cache invalidation after service calls.@handle_api_errors async def call_service(domain: str, service: str, data: Optional[Dict[str, Any]] = None) -> Dict[str, Any]: """Call a Home Assistant service""" if data is None: data = {} client = await get_client() response = await client.post( f"{HA_URL}/api/services/{domain}/{service}", headers=get_ha_headers(), json=data ) response.raise_for_status() # Invalidate cache after service calls as they might change entity states global _entities_timestamp _entities_timestamp = 0 return response.json()
- app/server.py:87-87 (registration)The @mcp.tool() decorator registers the entity_action function as an MCP tool (implicitly using the function name 'entity_action').@mcp.tool()
- app/server.py:89-111 (schema)Type hints and detailed docstring define the input schema (entity_id:str required, action:str required with validation to 'on'/'off'/'toggle', optional params:Dict), output dict from HA service response, plus usage examples and domain-specific param guidance.async def entity_action(entity_id: str, action: str, params: Optional[Dict[str, Any]] = None) -> dict: """ Perform an action on a Home Assistant entity (on, off, toggle) Args: entity_id: The entity ID to control (e.g. 'light.living_room') action: The action to perform ('on', 'off', 'toggle') params: Optional dictionary of additional parameters for the service call Returns: The response from Home Assistant Examples: entity_id="light.living_room", action="on", params={"brightness": 255} entity_id="switch.garden_lights", action="off" entity_id="climate.living_room", action="on", params={"temperature": 22.5} Domain-Specific Parameters: - Lights: brightness (0-255), color_temp, rgb_color, transition, effect - Covers: position (0-100), tilt_position - Climate: temperature, target_temp_high, target_temp_low, hvac_mode - Media players: source, volume_level (0-1) """