WhatsApp MCP Server

Instructions

Implementation Reference

• src/whatsapp_mcp/whatsapp_client.py:107-123 (handler)

  The core logic for checking if WhatsApp Web is ready, including timeout handling and state detection.

  async def wait_until_ready(self, timeout_seconds: int | None = None) -> dict[str, Any]:
      await self.ensure_started()
      timeout = timeout_seconds or self.settings.startup_timeout_seconds
      deadline = asyncio.get_running_loop().time() + timeout
  
      while asyncio.get_running_loop().time() < deadline:
          state = await self._detect_state()
          if state == "ready":
              return {"state": state, "ready": True}
          await asyncio.sleep(2)
  
      state = await self._detect_state()
      return {
          "state": state,
          "ready": state == "ready",
          "message": "WhatsApp Web did not become ready before timeout.",
      }

• src/whatsapp_mcp/mcp_server.py:156-167 (registration)

  Registration of the 'wait_until_ready' tool within the MCP server.

  "wait_until_ready": ToolDefinition(
      name="wait_until_ready",
      description="Wait until WhatsApp Web is fully authenticated and ready for use.",
      input_schema={
          "type": "object",
          "properties": {
              "timeout_seconds": {"type": "integer", "minimum": 5, "maximum": 600},
          },
          "additionalProperties": False,
      },
      handler=lambda args: self.client.wait_until_ready(args.get("timeout_seconds")),
  ),