🟢 WhatsApp MCP Server (24/7 Cloud & Local Edition)

An open-source Model Context Protocol (MCP) server that connects personal WhatsApp accounts directly to AI agents (Gemini Spark, Claude Desktop, Cursor, VS Code).

Designed for 100% Free 24/7/365 Cloud Hosting via Docker (Render, Koyeb, Railway, Cloud VMs) or local execution.

---

📐 Architecture Overview

graph TD
    A[WhatsApp Web API] <-->|WebSocket| B[Go WhatsApp Bridge :8080]
    B <-->|SQLite DB / REST| C[Python MCP Server]
    C <-->|SSE Proxy / stdio| D[Supergateway :8000]
    D <-->|HTTPS Tunnel / Cloud| E[AI Assistants: Gemini Spark / Claude / Cursor]

---

✨ Features

• 📱 Multi-Device WhatsApp Connect: Powered by whatsmeow with fast SQLite message syncing.
• ⚡ Pure-Go Build: No CGO/GCC compilation requirements on Windows/Linux.
• ☁️ 24/7 Cloud Dockerized: Deploy to Render.com, Koyeb, or Oracle Cloud for zero-cost continuous hosting without keeping your computer on.
• 🌐 Gemini Spark Ready: Built-in Server-Sent Events (SSE) server for instant web LLM connection.
• 🔒 Security First: Automatically ignores sensitive SQLite database session stores (whatsapp.db) to prevent credential leaks.

---

🛠️ Available MCP Tools

Tool Name	Description
search_contacts	Search contacts/groups by name or phone number
list_chats	View active chat conversations
list_messages	Retrieve recent message history from specific chats
send_message	Send text messages to individuals or groups
send_file	Send documents, photos, or media files
send_audio_message	Send playable voice notes (requires FFmpeg)

---

☁️ 1-Click Cloud Deployment (24/7 365-Day Free)

Deploy to Render / Koyeb

1. Fork or Clone this repository to your GitHub account.
2. Go to Render.com or Koyeb.com.
3. Create a New Web Service -> Connect your GitHub repository.
4. Select Docker environment.
5. Mount a Persistent Disk to /app/whatsapp-bridge/store.
6. Open container Logs during initial deploy to scan the WhatsApp QR code.
7. Connect your generated public SSE URL (https://your-app.onrender.com/sse) to Gemini Spark.

---

🖥️ Local Installation

Prerequisites

• Go v1.20+
• Python v3.11+
• uv package manager

Quick Start

# Clone repository
git clone https://github.com/VR-WebSpider/whatsapp-mcp-247.git
cd whatsapp-mcp-247

# Build Go bridge
cd whatsapp-bridge
go build -o whatsapp-bridge.exe .

# Install Python dependencies
cd ../whatsapp-mcp-server
uv sync

# Run complete stack
..\start_whatsapp_mcp.bat

---

🔒 Security Measures & Best Practices

1. Session Protection: SQLite databases (whatsapp.db, messages.db) contain sensitive authentication tokens and are explicitly ignored by .gitignore. Never commit .db files to public repositories.
2. Localhost Binding: The Go REST API binds to 127.0.0.1:8080 to prevent unauthorized local network access.
3. Public Tunnels: When using Cloudflare Tunnels for web LLMs, do not share your generated trycloudflare.com URL publicly.

---

📄 License

Distributed under the MIT License. See LICENSE for more information.