WACrew

Guide

How to connect WhatsApp to MCP, in any client

Connect WhatsApp to MCP in three steps, run the collector, pair the number and register one server, with the exact config for Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI and Antigravity.

Updated 2 min read
On this page
  1. Step 1: run the collector
  2. Step 2: pair your number
  3. Step 3: register the MCP server in your client
  4. Test it
  5. Before the agent sends anything
  6. FAQ

To connect WhatsApp to MCP you need two pieces: something that stays connected to WhatsApp and stores the messages, and an MCP server your AI client can start. With WACrew, the first is a small collector you host and the second is one npm package, wacrew-mcp, that every MCP client can run.

Step 1: run the collector

The collector is the part that holds your WhatsApp session 24/7. On any VPS with Docker:

git clone https://github.com/sumioshi/wacrew && cd wacrew
PANEL_USER=admin PANEL_PASS=change-me docker compose up -d

Railway also deploys it in one click from the README. Put HTTPS in front of the panel before exposing it.

Step 2: pair your number

Open http://<server>:3000/config and scan the QR code under WhatsApp, Linked devices. From now on every group and chat is stored, voice notes included.

Step 3: register the MCP server in your client

The server is the same everywhere: npx -y wacrew-mcp with three variables, WAC_CLOUD_URL (your panel), WAC_CLOUD_USER and WAC_CLOUD_PASS (the panel login). Only the place you write it changes.

clientwhereguide
Claude Codeclaude mcp add wacrew -e WAC_CLOUD_URL=... -e WAC_CLOUD_USER=... -e WAC_CLOUD_PASS=... -- npx -y wacrew-mcpClaude Code
Claude Desktopclaude_desktop_config.json, key mcpServersClaude Desktop
Codex~/.codex/config.toml, table [mcp_servers.wacrew]Codex
Cursor~/.cursor/mcp.json, key mcpServersCursor
Gemini CLI~/.gemini/settings.json, key mcpServersGemini CLI
Antigravityagy plugin install https://github.com/sumioshi/wacrewAntigravity

For the JSON clients the block is identical:

{
  "mcpServers": {
    "wacrew": {
      "command": "npx",
      "args": ["-y", "wacrew-mcp"],
      "env": {
        "WAC_CLOUD_URL": "https://your-panel.example.com",
        "WAC_CLOUD_USER": "admin",
        "WAC_CLOUD_PASS": "change-me"
      }
    }
  }
}

Node 20 or newer has to be installed where the client runs, because npx starts the server.

Test it

Restart the client and ask: "list my WhatsApp groups". The agent should call listar_grupos and answer with your chats. Then try "who is waiting for a reply?", which uses caixa_de_entrada. Tool names are in Portuguese because the project started in Brazil; their descriptions are in plain language and models pick them without trouble.

Before the agent sends anything

Every chat starts in confirm mode: the agent is told to show you the text and wait for your OK. Replies go through a review that refuses robotic text, and leave as a ticket with human pacing that you can cancel. Turn a chat to auto only when you trust it there. See WhatsApp MCP security for the rest.

FAQ

Do I need the collector, or can the MCP server talk to WhatsApp directly? Something has to stay connected to receive messages while your laptop sleeps. The collector does that; the MCP server only talks to it.

Can I connect more than one WhatsApp number? Yes, one server can hold several panels. See multiple WhatsApp accounts in one MCP server.

Is this the official WhatsApp API? No. The collector connects as a linked device through Baileys. Use it with people who already talk to you, not for bulk messaging.

Which clients support MCP? Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI, Antigravity, Qwen Code and many more. Any client that runs stdio MCP servers works.