Send to HomeAssistant Mobile APP

Instructions

Implementation Reference

• mcp_notify/__init__.py:22-22 (registration)

  Registration of hass tools (including ha_send_mobile) via hass.add_tools(mcp)

  hass.add_tools(mcp)

• mcp_notify/hass.py:38-94 (handler)

  Main tool registration and handler: defines the @mcp.tool decorator and the ha_send_mobile function that sends notifications to Home Assistant Mobile App via its REST API

  @mcp.tool(
      title="Send to HomeAssistant Mobile APP",
      description="Send a notification to Home Assistant Mobile APP",
  )
  def ha_send_mobile(
      message: str = Field(description="Notification content"),
      title: str = Field("", description="Notification title"),
      subtitle: str = Field("", description="Notification subtitle"),
      data: str | dict = Field("{}", description=f"Extended data, json string.{HA_NOTIFY_DATA_PROMPT}"),
      url: str = Field("", description="Opening a URL when tapping on a notification"),
      device_key: str = Field("", description="Device key, Default to get from environment variables"),
  ):
      base = os.getenv("HASS_BASE_URL") or "http://homeassistant.local:8123"
      if not (token := os.getenv("HASS_ACCESS_TOKEN")):
          return "You need to set `HASS_ACCESS_TOKEN` in the environment variable"
  
      headers = {"Authorization": f"Bearer {token}"}
      if not device_key:
          device_key = os.getenv("HASS_MOBILE_KEY", "")
      if not device_key:
          res = requests.get(f"{base}/api/services", headers=headers)
          for service in res.json() or []:
              if service["domain"] != "notify":
                  continue
              for name in service["services"]:
                  if name.startswith("mobile_app_"):
                      device_key = name
                      break
      if device_key.startswith("notify."):
          device_key = device_key[7:]
      elif not device_key.startswith("mobile_app_"):
          device_key = f"mobile_app_{device_key}"
  
      if isinstance(data, str):
          try:
              data = json.loads(data)
          except ValueError:
              data = {}
      elif not isinstance(data, dict):
          data = {}
      if url:
          data.setdefault("url", url)  # ios
          data.setdefault("clickAction", url)  # android
      if subtitle:
          data.setdefault("subtitle", subtitle)  # ios
          data.setdefault("subject", subtitle)  # android
  
      res = requests.post(
          f"{base}/api/services/notify/{device_key}",
          json={
              "message": message,
              "title": title,
              "data": data,
          },
          headers=headers,
      )
      return res.json()

• mcp_notify/hass.py:38-41 (registration)

  The @mcp.tool decorator registers ha_send_mobile as a tool with title and description

  @mcp.tool(
      title="Send to HomeAssistant Mobile APP",
      description="Send a notification to Home Assistant Mobile APP",
  )

• mcp_notify/hass.py:42-49 (schema)

  Input schema/parameters for ha_send_mobile: message (required), title, subtitle, data (extended JSON data), url, device_key

  def ha_send_mobile(
      message: str = Field(description="Notification content"),
      title: str = Field("", description="Notification title"),
      subtitle: str = Field("", description="Notification subtitle"),
      data: str | dict = Field("{}", description=f"Extended data, json string.{HA_NOTIFY_DATA_PROMPT}"),
      url: str = Field("", description="Opening a URL when tapping on a notification"),
      device_key: str = Field("", description="Device key, Default to get from environment variables"),
  ):