call_service_tool
Invoke Home Assistant services directly using domain and service parameters, with optional data for precise control of smart home devices and automations.
Instructions
Call any Home Assistant service (low-level API access)
Args: domain: The domain of the service (e.g., 'light', 'switch', 'automation') service: The service to call (e.g., 'turn_on', 'turn_off', 'toggle') data: Optional data to pass to the service (e.g., {'entity_id': 'light.living_room'})
Returns: The response from Home Assistant (usually empty for successful calls)
Examples: domain='light', service='turn_on', data={'entity_id': 'light.x', 'brightness': 255} domain='automation', service='reload' domain='fan', service='set_percentage', data={'entity_id': 'fan.x', 'percentage': 50}
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| data | No | ||
| domain | Yes | ||
| service | Yes |
Implementation Reference
- app/server.py:881-902 (handler)Primary MCP tool handler for 'call_service_tool'. Decorated with @mcp.tool() for registration. Logs the service call and delegates execution to the hass.call_service helper function.@async_handler("call_service") async def call_service_tool(domain: str, service: str, data: Optional[Dict[str, Any]] = None) -> Dict[str, Any]: """ Call any Home Assistant service (low-level API access) Args: domain: The domain of the service (e.g., 'light', 'switch', 'automation') service: The service to call (e.g., 'turn_on', 'turn_off', 'toggle') data: Optional data to pass to the service (e.g., {'entity_id': 'light.living_room'}) Returns: The response from Home Assistant (usually empty for successful calls) Examples: domain='light', service='turn_on', data={'entity_id': 'light.x', 'brightness': 255} domain='automation', service='reload' domain='fan', service='set_percentage', data={'entity_id': 'fan.x', 'percentage': 50} """ logger.info(f"Calling Home Assistant service: {domain}.{service} with data: {data}") return await call_service(domain, service, data or {})
- app/hass.py:312-330 (helper)Core implementation helper that makes the HTTP POST request to Home Assistant's /api/services/{domain}/{service} endpoint with the provided data.@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:881-881 (registration)MCP tool registration decorator applied to the call_service_tool handler function.@async_handler("call_service")