Hass-MCP

Instructions

Implementation Reference

• app/server.py:880-902 (handler)

  The primary MCP tool handler function 'call_service_tool' that provides the interface for calling arbitrary Home Assistant services. Registered via @mcp.tool() decorator.

  @mcp.tool()
  @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:313-331 (helper)

  Supporting helper function that performs the actual HTTP API call to Home Assistant's services endpoint. Imported and used by the main tool handler.

  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()