WhatsApp Connect

What the WhatsApp Connect MCP server does

The WhatsApp Connect MCP server gives MCP clients access to a paired personal WhatsApp account. Its read capabilities cover chats, messages, contacts, groups, calls, blocked contacts, message context, attachments, and newly received messages. Search can run across message bodies globally or within a selected chat, while time-based queries accept named windows, dates with an IANA time zone, or explicit timestamp bounds.

Agents can also request older messages from the phone, retrieve group membership and metadata, and download media into the local data directory. Outbound operations are separate from the read tools and protected by a server-enforced send confirmation gate. The project describes the server as a personal messaging tool, not a platform for unsolicited outreach, support automation, or high-volume sending.

How it works

WhatsApp Connect MCP server communicates with WhatsApp through whatsmeow, following the unofficial protocol used by WhatsApp Web rather than the official WhatsApp Business API. Pairing requires displaying a QR code and scanning it in WhatsApp under Linked Devices. The paired phone determines how much history is available; requesting full history can ask for more data during pairing, but does not guarantee that all historical messages will be provided.

The default stdio transport lets each MCP client start its own server process. Because the data directory has an exclusive lock, only one client or session can use that mode at a time. The HTTP transport runs one local server, protected by a bearer token, so multiple clients or sessions can connect to it. The HTTP process must be started separately and kept running.

Setup and configuration

Installers are provided for macOS, Linux, and Windows, and an npm package can be used where Node.js is available. The setup command downloads or uses the binary, performs QR pairing, detects installed MCP clients, and offers to add a whatsapp server entry. It can be run again to pair another account or configure a newly installed client.

Choose stdio for the simplest single-client arrangement. Choose HTTP when several clients need one local server, then start it with a bind address and port; the documented default port is 2178. The server can also be installed as a user background service using the platform's launchd, systemd, or Task Scheduler facilities. Read access can initially cover every chat, only the self-chat, or no chats until an allowlist is configured. The --full-history option only affects a fresh pairing.

Tools and capabilities

The server exposes 24 tools: 14 read-oriented tools and 10 outbound or otherwise gated tools. Read tools include:

• Listing and inspecting chats, messages, contacts, groups, calls, and the blocklist.
• Searching message text and obtaining nearby context for a matching message.
• Polling for new messages without repeatedly reading a chat.
• Fetching older messages and downloading one or more media attachments.
• Running diagnostics through the doctor tool.

Write operations require confirmation through the send gate. This lets an agent prepare a reply while leaving the actual outbound action subject to approval.

Limitations and notes

The WhatsApp Connect MCP server is pre-release software and uses an unofficial connection method. WhatsApp may identify third-party clients and ban paired numbers; the project warns that reported bans can be permanent. The confirmation gate and rate limiter address accidental or uncontrolled sending, but they cannot remove the risk associated with using a third-party protocol.

History depth is controlled by the paired phone and the protocol, so a request to search all history may reach only a limited period. The HTTP server is local in the documented setup and must remain running; a foreground process stops when its terminal ends. Pair a number that can be lost, and avoid using this tool for unsolicited or high-volume messaging.