WhatsApp MCP Server

What is WhatsApp MCP Server?

WhatsApp MCP Server is a Model Context Protocol (MCP) server that integrates your personal WhatsApp account with AI assistants like Claude or Cursor. It allows you to search and read messages (including images, videos, documents, and audio), search contacts, and send messages to individuals or groups via the WhatsApp web multidevice API.

How to use WhatsApp MCP Server?

Clone the repository, then run the Go bridge (go run main.go in whatsapp-bridge/) and scan the QR code with your WhatsApp mobile app to authenticate. Next, configure the Python MCP server by adding a JSON entry to your claude_desktop_config.json or mcp.json with the path to uv and the directory of whatsapp-mcp-server/. Restart Claude Desktop or Cursor to start using the integration.

Key features of WhatsApp MCP Server

• Search and read personal WhatsApp messages including media
• Send text messages to individuals or groups
• Send media files (images, videos, documents, audio)
• Search contacts by name or phone number
• All message history stored locally in SQLite
• Download media from messages for local access

Use cases of WhatsApp MCP Server

• Retrieve past conversations and media files via AI chat
• Send automated messages or media to contacts/clients
• Search for specific contacts or messages in large chat histories
• Get context around a specific message for analysis or summarization

FAQ from WhatsApp MCP Server

How does authentication work?

Authentication is done by scanning a QR code using your WhatsApp mobile app. The session typically lasts up to 20 days before re-authentication is needed. The Go bridge handles automatic reconnection if a session is already active.

What are the runtime dependencies?

You need Go, Python 3.6+, the Anthropic Claude Desktop app (or Cursor), and the UV Python package manager. FFmpeg is optional but required for sending non-Opus audio files as voice messages.

Where is my message data stored?

All message history is stored locally in a SQLite database located in the whatsapp-bridge/store/ directory. Data is only sent to the AI when you explicitly use the tools.

Can I use this server on Windows?

Yes, but you need to enable CGO and have a C compiler installed (e.g., via MSYS2) because go-sqlite3 requires CGO to compile on Windows.

What happens if I hit a device limit or my messages go out of sync?

WhatsApp limits linked devices. To resolve sync issues, delete both database files (messages.db and whatsapp.db in store/) and restart the bridge to re-authenticate. You may need to remove a device from WhatsApp mobile first (Settings > Linked Devices).