WhatsApp MCP — Claude Code MCP server: what it does, install
Connect Claude Code to WhatsApp chats, contacts, and messages. The server supports local voice-note transcription and a confirmation step before sending.
claude mcp add --env WHATSAPP_BRIDGE_HOST=<WHATSAPP_BRIDGE_HOST> --env WHATSAPP_BRIDGE_PORT=<WHATSAPP_BRIDGE_PORT> --env WHATSAPP_VAULT_CRM_PATH=<WHATSAPP_VAULT_CRM_PATH> --env WHATSAPP_WHISPER_BACKEND=<WHATSAPP_WHISPER_BACKEND> --env WHATSAPP_WHISPER_API_KEY=<WHATSAPP_WHISPER_API_KEY> --transport stdio whatsapp-mcp -- uvx adelaidasofia-whatsapp-mcpWhat WhatsApp MCP does
WhatsApp MCP lets an agent read chats, messages, and contacts, then search message history with typo- and accent-tolerant matching. It can resolve LID names, attach matching CRM context from an Obsidian vault, and transcribe voice notes on the same machine with whisper.cpp.
The setup has two local parts: the Go whatsapp-bridge/ and the Python whatsapp-mcp-server/ built with FastMCP. The bridge uses whatsmeow, keeps data in an encrypted SQLCipher database, and exposes a REST API to the Python layer. Outbound text, reactions, and quoted replies stay behind a draft plus mandatory confirm_send step; tool calls go to an audit log.
The bridge needs a one-time QR pairing with your phone before it can connect to WhatsApp. That pairing is a prerequisite, not an optional setup detail. Voice transcription needs FFmpeg and whisper.cpp; choosing openai-api also requires WHATSAPP_WHISPER_API_KEY.
What it helps with
- read WhatsApp chats and contacts from an agent
- search messages despite accents or typos
- transcribe voice notes on the local machine
- draft a reply before it is sent
- bring Obsidian CRM context into chat work
Example prompts for the agent
- Search WhatsApp for messages about the release, allowing for typos and accents.
- Show the latest messages in this chat and include matching CRM context from the Obsidian vault.
- Draft a reply to the latest message, show it to me, and send it only after
confirm_send.
How to install WhatsApp MCP
Platform CLI
claude mcp add --env WHATSAPP_BRIDGE_HOST=<WHATSAPP_BRIDGE_HOST> --env WHATSAPP_BRIDGE_PORT=<WHATSAPP_BRIDGE_PORT> --env WHATSAPP_VAULT_CRM_PATH=<WHATSAPP_VAULT_CRM_PATH> --env WHATSAPP_WHISPER_BACKEND=<WHATSAPP_WHISPER_BACKEND> --env WHATSAPP_WHISPER_API_KEY=<WHATSAPP_WHISPER_API_KEY> --transport stdio whatsapp-mcp -- uvx adelaidasofia-whatsapp-mcpReplace <…> with your own values. 4 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from adelaidasofia-whatsapp-mcp <command>
Platform CLI
codex mcp add whatsapp-mcp --env WHATSAPP_BRIDGE_HOST=<WHATSAPP_BRIDGE_HOST> --env WHATSAPP_BRIDGE_PORT=<WHATSAPP_BRIDGE_PORT> --env WHATSAPP_VAULT_CRM_PATH=<WHATSAPP_VAULT_CRM_PATH> --env WHATSAPP_WHISPER_BACKEND=<WHATSAPP_WHISPER_BACKEND> --env WHATSAPP_WHISPER_API_KEY=<WHATSAPP_WHISPER_API_KEY> -- uvx adelaidasofia-whatsapp-mcpReplace <…> with your own values. 4 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from adelaidasofia-whatsapp-mcp <command>
Config file
{
"mcpServers": {
"whatsapp-mcp": {
"command": "uvx",
"args": [
"adelaidasofia-whatsapp-mcp"
],
"env": {
"WHATSAPP_BRIDGE_HOST": "<WHATSAPP_BRIDGE_HOST>",
"WHATSAPP_BRIDGE_PORT": "<WHATSAPP_BRIDGE_PORT>",
"WHATSAPP_VAULT_CRM_PATH": "<WHATSAPP_VAULT_CRM_PATH>",
"WHATSAPP_WHISPER_BACKEND": "<WHATSAPP_WHISPER_BACKEND>",
"WHATSAPP_WHISPER_API_KEY": "<WHATSAPP_WHISPER_API_KEY>"
}
}
}
}Replace <…> with your own values. 4 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from adelaidasofia-whatsapp-mcp <command>
Config file
{
"servers": {
"whatsapp-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"adelaidasofia-whatsapp-mcp"
],
"env": {
"WHATSAPP_BRIDGE_HOST": "<WHATSAPP_BRIDGE_HOST>",
"WHATSAPP_BRIDGE_PORT": "<WHATSAPP_BRIDGE_PORT>",
"WHATSAPP_VAULT_CRM_PATH": "<WHATSAPP_VAULT_CRM_PATH>",
"WHATSAPP_WHISPER_BACKEND": "<WHATSAPP_WHISPER_BACKEND>",
"WHATSAPP_WHISPER_API_KEY": "<WHATSAPP_WHISPER_API_KEY>"
}
}
}
}Replace <…> with your own values. 4 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from adelaidasofia-whatsapp-mcp <command>
Platform CLI
gemini mcp add -e WHATSAPP_BRIDGE_HOST=<WHATSAPP_BRIDGE_HOST> -e WHATSAPP_BRIDGE_PORT=<WHATSAPP_BRIDGE_PORT> -e WHATSAPP_VAULT_CRM_PATH=<WHATSAPP_VAULT_CRM_PATH> -e WHATSAPP_WHISPER_BACKEND=<WHATSAPP_WHISPER_BACKEND> -e WHATSAPP_WHISPER_API_KEY=<WHATSAPP_WHISPER_API_KEY> whatsapp-mcp uvx adelaidasofia-whatsapp-mcpReplace <…> with your own values. 4 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from adelaidasofia-whatsapp-mcp <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about WhatsApp MCP
How do I install WhatsApp MCP in Claude Code?
Run claude mcp add whatsapp-mcp -e WHATSAPP_WHISPER_API_KEY=<WHATSAPP_WHISPER_API_KEY> -- uvx adelaidasofia-whatsapp-mcp.
What does WhatsApp MCP do?
It gives Claude Code access to WhatsApp chats, messages, and contacts, with message search and voice-note transcription. Text sends, reactions, and quoted replies require confirm_send before delivery.
What does WhatsApp MCP need to connect?
Start the Go bridge and complete the one-time QR pairing with your phone. FFmpeg and whisper.cpp are needed for voice transcription, while the openai-api backend requires WHATSAPP_WHISPER_API_KEY.
