whatsapp

This MCP server bridges WhatsApp conversations to MCP clients, exposing tools, prompts, and resources that let an AI assistant read, search, and interact with your WhatsApp messages. It uses a local WhatsApp client backed by SQLite for storage, and provides an HTTP+SSE API that MCP clients can stream from. You can connect to Claude Desktop or any MCP-compatible client by pointing the client to http://localhost:8080/mcp/{API_KEY} with API key authentication. Core capabilities include listing chats, reading messages with pagination, performing cross-chat searches, locating chats by name, sending messages, loading older history on demand, and retrieving your own profile info. Prompts guide AI workflows such as searching messages by person, analyzing conversations, and keyword-based search, while resources offer embedded guides for workflow and formatting, JID formats, and search patterns.

Prerequisites:

• Go 1.25+ for local setup or Docker (recommended)
• Git
• WhatsApp account to link via QR code
• MCP-compatible AI client

Option A: Docker Setup (Recommended)

1. Install Docker on your system.
2. Clone the repository or use the image directly:
   • docker pull felipeadeildo/whatsapp-mcp:latest
3. Run the container with your API key and config:
   • docker run -d --name whatsapp-mcp -e API_KEY=your-api-key -e TIMEZONE=Your/Timezone felipeadeildo/whatsapp-mcp:latest
4. Link WhatsApp by viewing container logs and scanning the QR code that appears.
5. Verify the server is running:
   • curl http://localhost:8080/health

Option B: Local Go Setup (if you prefer running natively)

1. Prerequisites:
   • Go 1.25.5+
2. Clone the repo and install dependencies:
   • git clone https://github.com/felipeadeildo/whatsapp-mcp
   • cd whatsapp-mcp
   • go mod download
3. Configure environment:
   • cp .env.example .env
   • Edit .env with your settings (API key, timezone, etc.)
4. Run the server:
   • go run main.go
5. Link WhatsApp by scanning the QR code shown in the terminal.
6. Verify the server is running:
   • curl http://localhost:8080/health

Notes and tips:

• The MCP endpoint is exposed at /mcp/{API_KEY} and requires an API key for authentication.
• You can connect via HTTP+SSE from any MCP client.
• Ensure your .env (or environment) contains your API_KEY and timezone to keep timestamps accurate.
• If you experience QR code linking issues, check logs for WhatsApp connection status and ensure your network allows the WhatsApp Web session to establish.
• The server stores messages locally in SQLite for fast access and offline capability; consider regular backups of the database.
• For Docker deployments, prefer using the provided image tag and environment variables to avoid mismatches between local and container setups.