WhatsApp MCP Server

Instructions

Implementation Reference

• src/whatsapp_mcp/whatsapp_client.py:125-142 (handler)

  The `list_recent_chats` handler in `WhatsAppClient` class, which uses Playwright to scrape chat information from the DOM.

  async def list_recent_chats(self, limit: int = 20) -> dict[str, Any]:
      await self._require_ready()
      assert self._page is not None
  
      await self._page.goto(self.settings.base_url, wait_until="domcontentloaded")
      await self._page.wait_for_selector(READY_SELECTORS[0])
      chats = await self._page.evaluate(
          """(limit) => {
              const rows = Array.from(document.querySelectorAll('#pane-side [role="listitem"]')).slice(0, limit);
              return rows.map((row, index) => {
                  const title = row.querySelector('[title]')?.getAttribute('title') || null;
                  const preview = row.innerText ? row.innerText.split('\\n').slice(0, 4).join(' | ') : null;
                  return { index, title, preview };
              });
          }""",
          limit,
      )
      return {"count": len(chats), "chats": chats}

• src/whatsapp_mcp/mcp_server.py:168-179 (registration)

  Registration of the `list_recent_chats` tool in the `WhatsAppMCPServer` class, mapping the tool to its handler.

  "list_recent_chats": ToolDefinition(
      name="list_recent_chats",
      description="List the most recent chats visible in WhatsApp Web.",
      input_schema={
          "type": "object",
          "properties": {
              "limit": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20},
          },
          "additionalProperties": False,
      },
      handler=lambda args: self.client.list_recent_chats(args.get("limit", 20)),
  ),