Best for
- Individual users who want to manage WhatsApp messages with an AI assistant while keeping local message records
- Developers needing programmatic access to WhatsApp chat data
W
WhatsApp MCP
Community
Read, search, and send WhatsApp messages via Claude
GitHub source repository ↗
54FMRS · D
The server is feature-rich, supporting a variety of message operations and media handling. However, security risks and compliance issues with the unofficial API should be noted. It is suitable for personal or development use; for production, careful evaluation is required.
This is a Model Context Protocol (MCP) server that connects Claude to WhatsApp, enabling message reading, searching, and sending. It consists of a Python MCP server and a Go bridge that interacts with WhatsApp via the WhatsApp Web API, storing messages locally in SQLite. The server provides tools for contact search, message listing, chat management, media send/download, and webhook forwarding of incoming messages.
Tools
search_contacts
Search contacts by name or phone number
get_contact
Resolve phone number to contact name
list_messages
Get messages with filters, date ranges, and sorting
list_chats
List all chats with metadata
get_chat
Get specific chat metadata by JID
get_direct_chat_by_contact
Find direct message chat with a contact
get_contact_chats
List all chats involving a contact
get_last_interaction
Get last message with a contact
get_message_context
Get messages around a specific message
send_message
Send text message to contact or group
send_reaction
Send (or remove) an emoji reaction to a message
send_file
Send media file (image, video, document)
send_audio_message
Send voice message (auto-converts to Opus)
download_media
Download media from a received message
Setup
- Clone the repository and navigate to the directory. 2. Start the Go bridge:
cd whatsapp-bridge && go run .. On first start, scan the QR code to authenticate. 3. Add the MCP server configuration to Claude Desktop's config file (claude_desktop_config.json) or Cursor's config (~/.cursor/mcp.json) using the uv command with the whatsapp-mcp-server directory. 4. Restart Claude Desktop or Cursor.
claude_desktop_config.json
{
"mcpServers": {
"whatsapp": {
"command": "uv",
"args": [
"--directory",
"/path/to/whatsapp-mcp/whatsapp-mcp-server",
"run",
"main.py"
]
}
}
}
Fit and risk
Not for
- Environments with high security requirements for WhatsApp messages (prompt injection risks)
- Large enterprise deployments requiring official WhatsApp API support (this server uses unofficial Web API)
- Multi-user setups or those needing fine-grained access control (current implementation is single-user)
Required permissions
- Read and send WhatsApp messages (via bridge)
- Read and write message history in local SQLite database
- Send and receive media files
- Access local file system (for media file paths)
- Listen on local REST API port (default 8080)
Risks and side effects
- Prompt injection: malicious messages could trick the AI into performing unintended actions, leading to data exfiltration
- Unofficial API: uses reverse-engineered WhatsApp Web API, potentially violating WhatsApp's terms of service
- Sensitive data exposure: messages are stored locally, but the AI might send content to external services
- No authentication: the MCP server itself has no authentication, and if exposed to network, it can be abused
Troubleshooting
- QR code not displaying: restart the bridge, check terminal QR code support
- Device limit reached: remove a linked device from WhatsApp Settings > Linked Devices
- No messages loading: initial sync may take several minutes; ensure bridge is running
- Bridge returns 401 Unauthorized: restart bridge to generate .bridge-token, then restart MCP server
- Bridge returns 403 Forbidden for Host: ensure WHATSAPP_API_URL uses 127.0.0.1 or localhost
- Media path rejected: move file to default outbox or configure WHATSAPP_MEDIA_ROOTS
Use cases
Let Claude send WhatsApp messages to contacts
Query chat history and retrieve specific conversations
Automatically download received media files
Integrate WhatsApp messages into AI workflows
Supported clients
Claude DesktopFull support
CursorFull support