WhatsApp MCP
by lharries
Read and send WhatsApp messages from your AI assistant
communication Python Intermediate Self-hostable No API key
⭐ 5.4k stars 📅 Updated: 1mo ago
Description
An MCP server that connects your personal WhatsApp account to Claude, Cursor, and other AI assistants. Uses the whatsmeow library (Go) to connect via WhatsApp's web multidevice API with QR code authentication. Messages are stored locally in SQLite with full user control over data. Supports searching contacts, reading messages (text, images, videos, documents, audio), sending messages to individuals and groups, and downloading media files. Includes automatic audio format conversion via FFmpeg. Architecture splits into a Go bridge for WhatsApp connectivity and a Python MCP server for the AI interface.
✅ Best for
Power users who want AI assistants with full WhatsApp access on their local machine
⏭️ Skip if
You need a production-ready or enterprise WhatsApp integration
💡 Use cases
- Reading and searching WhatsApp message history from AI assistants
- Sending WhatsApp messages via natural language commands
- Extracting and analyzing conversation data for summaries or insights
- Automating WhatsApp responses and notifications
👍 Pros
- ✓ Direct WhatsApp integration without third-party APIs or business accounts
- ✓ Local-only data storage — messages stay on your machine
- ✓ Supports all media types (text, images, video, audio, documents)
- ✓ Large community (5k+ stars) with active development
👎 Cons
- ✗ Requires Go and Python runtimes plus FFmpeg for audio
- ✗ QR code authentication needed on first setup (no API key)
- ✗ Security warning: prompt injection could enable data exfiltration
- ✗ No official npm/pip package — manual clone and setup required
🔧 Exposed tools (12 tools)
| Tool | Category | Description |
|---|---|---|
| search_contacts | contacts | Search WhatsApp contacts by name or number |
| send_file | media | Send a file to a contact or group |
| send_audio_message | media | Send an audio message with format conversion |
| download_media | media | Download media from a WhatsApp message |
| list_messages | messaging | List messages from a chat with pagination |
| list_chats | messaging | List all WhatsApp chats |
| get_chat | messaging | Get details of a specific chat |
| get_direct_chat_by_contact | messaging | Get direct chat with a contact |
| get_contact_chats | messaging | Get all chats involving a contact |
| get_last_interaction | messaging | Get the last interaction with a contact |
| get_message_context | messaging | Get messages surrounding a specific message |
| send_message | messaging | Send a text message to a contact or group |
⚡ Installation
Prerequisites:
- • python v3.6+
- • go
- • uv
- • ffmpeg
Check Claude Code documentation to configure this MCP server.
💡 Tips & tricks
Run the Go bridge first with 'go run main.go' and scan the QR code before starting the MCP server. FFmpeg is optional but needed for audio message support.
Quick info
- Author
- lharries
- License
- MIT
- Runtime
- Python 3.6+
- Transport
- —
- Category
- communication
- Difficulty
- Intermediate
- Self-hostable
- ✅
- Auth
- —
- Docker
- —
- Version
- 0.0.1
- Updated
- Feb 28, 2026
Client compatibility
- ✅ Claude Code
- ✅ Cursor
- ❓ VS Code Copilot
- ❓ Gemini CLI
- ❓ Windsurf
- ❓ Cline
- ❓ JetBrains AI
- ❓ Warp
Platforms
🍎 macOS 🐧 Linux 🪟 Windows