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) andtranscreverfor 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_respostaandresponder.
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.
Step 1: install and link WhatsApp
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.
preparar_respostareturns your recent style in that chat and what the client left open.- The agent writes two or three drafts and you read them. To review without sending, there's
revisar_texto. respondertakes the drafts ascandidatosand 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.- 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_enviotracks it andcancelar_enviocancels 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
| Symptom | Likely cause | What to do |
|---|---|---|
The server doesn't show in /mcp | Claude Code was opened outside the repo folder, or .mcp.json doesn't exist | Open Claude Code at the repo root and check the file |
| The server fails to start | Panel dependencies weren't installed, so tsx is missing | Run npm --prefix web install |
| No groups show up | The number wasn't paired or the groups weren't selected | Open localhost:3000/config and check |
| Older messages are missing | Capture starts at pairing | Earlier history can't be imported |
| The reply "didn't go out" | Sending is ticket-based and slow on purpose | Check 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.



