WACrew

Blog

How to connect WhatsApp to Claude Code with MCP

Connect WhatsApp to Claude Code with MCP using WACrew's open-source server and its 36 tools. Install, pair the number, register the server, test reads, reply safely, and run it from the cloud. Also works in Codex, Cursor and Qwen Code.

Updated 6 min read
On this page
  1. What the agent can do once connected
  2. Before you start
  3. Step 1: install and link WhatsApp
  4. Step 2: register the MCP server in Claude Code
  5. Step 3: test with a read-only request
  6. Step 4: reply safely
  7. Codex, Cursor and other MCP clients
  8. Running 24/7 and reading from the cloud
  9. Common problems
  10. Where to go next

If you spend the day in a terminal with a coding agent, it makes sense for that agent to read what the client asked for on WhatsApp too. The way to do it is MCP (Model Context Protocol), an open standard that lets an agent like Claude Code call external tools, such as "read the messages in group X" or "transcribe this voice note". New to MCP? Start with What is MCP.

This guide shows how to connect WhatsApp to Claude Code with MCP using the server that ships with WACrew, which is open source and comes with 36 tools. The same server works in Codex, Qwen Code, Cursor and any MCP client.

What the agent can do once connected

With the server running, you talk to the agent in plain language and it picks the tools. Tool names are in Portuguese because the project started in Brazil, and their descriptions are clear enough for any model. Some requests that work:

  • "Who is waiting for a reply right now?" uses caixa_de_entrada (the inbox).
  • "What did the client ask for today in the project group?" uses ler_mensagens (read messages) and transcrever for voice notes.
  • "Look at the error screenshot he sent" uses ver_imagem, and the model actually sees the image.
  • "He sent a screen recording, what happens in it?" uses assistir_video.
  • "Find where we talked about the report deadline" uses buscar (search), which also finds text inside transcripts.
  • "Reply that the fix ships tomorrow" uses preparar_resposta and responder.

The real payoff comes when the conversation and the code live in the same place. The agent reads the bug reported in the group, opens the repository, fixes it and drafts the reply to the client without you switching windows.

Before you start

You'll need:

  • Node.js 20 or newer and ffmpeg.
  • A WhatsApp account to link as an extra device. Your work account is fine; your phone keeps working as usual.
  • Claude Code (or another MCP client) installed.
  • For transcribing audio on your own machine, a Mac with Apple Silicon. Elsewhere, transcription goes through an API.

One caveat worth reading now: WACrew does not use the official WhatsApp API. It connects through Baileys, the same way WhatsApp Web does. It's built for answering people who already talk to you. Bulk messaging and cold outreach can get the number banned.

Clone the repository and install the collector and panel dependencies:

git clone https://github.com/sumioshi/wacrew && cd wacrew
npm install && npm --prefix web install
npm run dev

npm run dev starts the collector, the panel, the transcriber and the notifier. Open http://localhost:3000/config, scan the QR code with your phone (WhatsApp › Linked devices › Link a device) and pick the groups to follow. The session is saved and reconnects on its own.

Capture starts at that moment. WACrew doesn't import older history, so the agent only sees what arrives after pairing.

Step 2: register the MCP server in Claude Code

The repository ships a ready-made project-scope config. Copy it:

cp .mcp.json.example .mcp.json

The file points to the server in web/mcp/server.ts and to the local data folder:

{
  "mcpServers": {
    "whatsapp-collector": {
      "command": "./web/node_modules/.bin/tsx",
      "args": ["./web/mcp/server.ts"],
      "env": {
        "WAC_DATA_DIR": "./data",
        "WAC_GROUPS_CONFIG": "./groups.config.json"
      }
    }
  }
}

Open Claude Code in the repository folder. It reads .mcp.json and asks for your approval the first time the server is used. Approve it and run /mcp to confirm whatsapp-collector shows as connected.

.mcp.json is kept out of git on purpose: if you put a password in it, it won't end up in the repository.

Step 3: test with a read-only request

Always start by reading, never by sending. Ask something like:

list the groups you can see and tell me who is waiting for a reply

The agent should call listar_grupos and caixa_de_entrada. If the list comes back empty, go back to the panel and check that the groups are marked to follow and that at least one message arrived after pairing.

Step 4: reply safely

Sending is the part that needs care, because sending is real: the message leaves your account and reaches your client. The recommended flow has four steps.

  1. preparar_resposta returns your recent style in that chat and what the client left open.
  2. The agent writes two or three drafts and you read them. To review without sending, there's revisar_texto.
  3. responder takes the drafts as candidatos and sends the one that sounds most like you. Before anything leaves, a review written in code blocks robotic phrasing, repeated apologies and repeated bubbles. If it blocks, nothing is sent.
  4. What you get back is a ticket, not a delivery confirmation. The message goes out later at a human pace: seconds in a live chat, minutes to hours in a cold one. status_envio tracks it and cancelar_envio cancels it.

Every chat has a mode. In Confirm, the default, the convention is that the agent shows you the text and waits for your OK before sending. In Autonomous, switched on per chat, it can answer on its own. Start everything in Confirm.

Run your first send test in a group that only you are in, created for that. Never test in a client group.

Codex, Cursor and other MCP clients

The server is the same; only where you register it changes. Qwen Code reads the same .mcp.json from the repo root and asks for approval the first time. In Codex, the server goes into the mcp_servers section of config.toml, with absolute paths so it doesn't depend on the folder Codex was opened in:

[mcp_servers.whatsapp-collector]
command = "/path/to/wacrew/web/node_modules/.bin/tsx"
args = ["/path/to/wacrew/web/mcp/server.ts"]
env = { WAC_DATA_DIR = "/path/to/wacrew/data", WAC_GROUPS_CONFIG = "/path/to/wacrew/groups.config.json" }

Any other client that speaks MCP over stdio follows the same idea: the tsx command, web/mcp/server.ts as the argument and the two environment variables.

Running 24/7 and reading from the cloud

With the collector only on your computer, messages that arrive while it's off are never captured. To avoid gaps, run the collector and panel on a server with the included Dockerfile or the prebuilt image (Railway works out of the box) and a volume at /data. Set PANEL_USER and PANEL_PASS so the panel requires a login.

Then your local MCP can read straight from the cloud panel. The npm package does it without cloning anything:

claude mcp add wacrew -e WAC_CLOUD_URL=https://your-panel.example.com \
  -e WAC_CLOUD_USER=admin -e WAC_CLOUD_PASS=change-me -- npx -y wacrew-mcp

Media is downloaded on demand when the agent asks to see or transcribe something.

Common problems

SymptomLikely causeWhat to do
The server doesn't show in /mcpClaude Code was opened outside the repo folder, or .mcp.json doesn't existOpen Claude Code at the repo root and check the file
The server fails to startPanel dependencies weren't installed, so tsx is missingRun npm --prefix web install
No groups show upThe number wasn't paired or the groups weren't selectedOpen localhost:3000/config and check
Older messages are missingCapture starts at pairingEarlier history can't be imported
The reply "didn't go out"Sending is ticket-based and slow on purposeCheck status_envio before trying again, so you don't send twice

Where to go next

For the server overview, with the full tool table and a comparison with other ways to connect WhatsApp to an agent, see the WhatsApp MCP server page, and WhatsApp MCP servers compared for the alternatives. To build your own agent loop on top, read how to build a WhatsApp AI agent with MCP. If something breaks, the WhatsApp MCP troubleshooting guide covers the common errors, and all related guides are in the WhatsApp MCP hub. The code is open source under Apache 2.0 on GitHub.