概览
What is WhatsApp MCP Server?
WhatsApp MCP Server is a Model Context Protocol server that connects your personal WhatsApp account to LLM clients like Claude, enabling reading/searching messages, managing contacts, and sending messages or media. It uses the WhatsApp web multidevice API via the whatsmeow library and stores all message history locally in a SQLite database.
How to use WhatsApp MCP Server?
Install Go, Python 3.6+, UV, and optionally FFmpeg. Clone the repository, run the Go WhatsApp bridge (go run main.go), scan the QR code for authentication, then configure the MCP client (Claude Desktop or Cursor) using the provided JSON with paths to UV and the Python server. Restart the client to see the integration.
Key features of WhatsApp MCP Server
- Search contacts by name or phone number
- List and filter messages with context
- View all chats with metadata
- Send text messages to individuals or groups
- Send media files (images, videos, documents, audio)
- Send audio files as WhatsApp voice messages (requires FFmpeg for conversion)
- Download media from messages to local file path
Use cases of WhatsApp MCP Server
- Retrieve and analyse old WhatsApp messages through an LLM
- Automate sending personalised messages to contacts
- Search chat history for specific information
- Send media files programmatically via AI instructions
- Manage WhatsApp conversations from within Claude Desktop
FAQ from WhatsApp MCP Server
How does it connect to my WhatsApp account?
It connects via the WhatsApp web multidevice API using the whatsmeow library. You authenticate by scanning a QR code with your WhatsApp mobile app. After approximately 20 days, you may need to re-authenticate.
Where is my message history stored?
All message history is stored locally in a SQLite database inside the whatsapp-bridge/store/ directory. Data is only sent to the LLM when you use the provided tools.
Can I send voice messages?
Yes, use the send_audio_message tool. Audio files must be in .ogg Opus format for playable voice messages, or you can install FFmpeg for automatic conversion. Without FFmpeg, you can send raw audio using send_file.
What are the system requirements?
You need Go, Python 3.6+, UV (Python package manager), and either Claude Desktop or Cursor. FFmpeg is optional but needed for automatic audio conversion when sending voice messages.
Does it work on Windows?
Yes, but you must enable CGO and install a C compiler (e.g., via MSYS2) for the go-sqlite3 dependency. Without this, you will get a CGO compilation error.
How can I troubleshoot authentication issues?
If the QR code doesn't appear, restart the Go bridge. If WhatsApp is out of sync, delete the database files (messages.db and whatsapp.db in store/) and restart. Also ensure you have not reached WhatsApp's device limit.
