How shreyasj14/whatsapp-bulkmsg works
Project type and purpose
• This is an open-source “integration tool” comprising two cooperating services:
a. A Go-based “WhatsApp Bridge” that connects your personal WhatsApp account (via the Whatsmeow library) to a local SQLite store.
b. A Python “MCP Server” that implements the Model Context Protocol, exposing tools that let an LLM (Claude or Cursor) interact with your WhatsApp data and send messages.
• Use case: Allow an LLM to search messages, list chats/contacts, and send WhatsApp messages under your control.
File structure
• Top-level:
• whatsapp-bridge/ ← Go module
• whatsapp-mcp-server/ ← Python MCP server
• sample_numbers.xlsx ← demo data
• whatsapp-bridge/
• main.go → entrypoint that authenticates via QR, maintains WebSocket to WhatsApp Web API, and syncs messages to SQLite.
• go.mod/go.sum → Go dependency management.
• whatsapp-mcp-server/
• main.py → Python UV-managed CLI that launches an HTTP/gRPC/MCP-compatible server.
• whatsapp.py → library module that wraps database queries and bridge RPC calls.
• send_bulk_whatsapp.py, create_sample_excel.py → utility scripts.
• pyproject.toml, uv.lock → Python dependencies via UV.
• SQLite DB files live under whatsapp-bridge/store/, and the Python server may read from them directly or via the bridge.
README insights
• Two main components (Go bridge + Python MCP server) are already described.
• Data flow summary:
1. Claude → Python MCP server
2. Python MCP server ↔ Go bridge or SQLite
3. Go bridge ↔ WhatsApp Web API → local SQLite
4. Responses flow back → Claude
• Key technologies: Go, Python3 (UV), SQLite, Whatsmeow, MCP.
a. Main components
• External Entities:
• WhatsApp Web API (via Whatsmeow)
• LLM Client (Claude Desktop or Cursor)
• Services:
• WhatsApp Bridge (Go)
• MCP Server (Python)
• Data Store:
• SQLite database
b. Relationships & Data Flows
c. Architectural patterns and principles
• Separation of concerns: Bridge handles protocol details and persistence; MCP server exposes a uniform toolset to the LLM.
• Microservice-style communication: Independent Go and Python processes connected via light RPC or shared DB.
• Data indexing and caching: SQLite stores and indexes chats/messages for efficient queries.
d. Key technologies/frameworks
• Go + whatsmeow for WhatsApp integration
• SQLite for local persistence
• Python + UV for MCP server
• MCP (Model Context Protocol) standard for LLM tool integration
• LLM clients: Claude Desktop, Cursor