WhatsApp MCP Server

Instructions

Implementation Reference

• src/whatsapp_mcp/whatsapp_client.py:165-239 (handler)

  The `get_recent_messages` method in `WhatsAppClient` which navigates to the chat and scrapes messages from the DOM.

  async def get_recent_messages(
      self,
      limit: int = 20,
      phone_number: str | None = None,
      chat_name: str | None = None,
  ) -> dict[str, Any]:
      await self._require_ready()
      assert self._page is not None
  
      target = await self._open_target_chat(phone_number=phone_number, chat_name=chat_name)
      await self._wait_for_message_box()
      await self._page.wait_for_timeout(1000)
      await self._load_message_history(limit)
  
      messages = await self._page.evaluate(
          """(limit) => {
              const selectors = [
                  '[data-testid="msg-container"]',
                  'div.message-in, div.message-out',
                  '[role="row"]'
              ];
              const seen = new Set();
              const nodes = [];
  
              for (const selector of selectors) {
                  for (const node of document.querySelectorAll(selector)) {
                      if (!(node instanceof HTMLElement)) continue;
                      if (seen.has(node)) continue;
                      const hasStructuredText = node.querySelector('[data-pre-plain-text]');
                      const hasVisibleText = Boolean(node.innerText && node.innerText.trim());
                      if (!hasStructuredText && !hasVisibleText) continue;
                      seen.add(node);
                      nodes.push(node);
                  }
              }
  
              const extracted = nodes.map((node) => {
                  const structuredText = Array.from(node.querySelectorAll('[data-pre-plain-text]'))
                      .map((el) => el instanceof HTMLElement ? el.innerText.trim() : '')
                      .filter(Boolean);
  
                  let text = structuredText.join('\\n').trim();
                  if (!text) {
                      text = (node.innerText || '').trim();
                  }
  
                  const outgoing =
                      node.matches('.message-out') ||
                      Boolean(node.querySelector('.message-out')) ||
                      Boolean(node.querySelector('[data-testid="msg-outgoing"]')) ||
                      Boolean(node.querySelector('[data-icon="msg-check"], [data-icon="msg-dblcheck"]'));
  
                  const incoming =
                      node.matches('.message-in') ||
                      Boolean(node.querySelector('.message-in')) ||
                      Boolean(node.querySelector('[data-testid="msg-incoming"]'));
  
                  const timestamp = node.querySelector('[data-pre-plain-text]')?.getAttribute('data-pre-plain-text') || null;
  
                  return {
                      direction: outgoing ? 'outgoing' : incoming ? 'incoming' : 'unknown',
                      text,
                      timestamp,
                  };
              }).filter((item) => item.text);
  
              return extracted.slice(-limit);
          }""",
          limit,
      )
      return {
          "target": target,
          "count": len(messages),
          "messages": messages,
      }

• src/whatsapp_mcp/mcp_server.py:199-217 (registration)

  The `get_recent_messages` tool definition and registration within the `WhatsAppMCPServer._build_tools` method.

  "get_recent_messages": ToolDefinition(
      name="get_recent_messages",
      description="Read recent messages from a chat identified by either a phone number or a chat name.",
      input_schema={
          "type": "object",
          "properties": {
              "phone_number": {"type": "string"},
              "chat_name": {"type": "string"},
              "limit": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20},
              "count": {"type": "integer", "minimum": 1, "maximum": 100, "description": "Alias for limit."},
          },
          "additionalProperties": False,
      },
      handler=lambda args: self.client.get_recent_messages(
          limit=args.get("limit", args.get("count", 20)),
          phone_number=args.get("phone_number"),
          chat_name=args.get("chat_name"),
      ),
  ),