From GitHub · · 1m 50s
GitHub - finereli/whatsapp-mcp
Read-only WhatsApp server for AI agents.
In brief
Read-only WhatsApp server for AI agents. A free open-source tool lets AI agents search encrypted WhatsApp messages without sending or editing them. Originally reported by GitHub.
What is WhatsApp MCP
A read-only MCP server that connects ChatGPT, Claude, or Grok to your WhatsApp messages.
How it works
Your phone stays the source of truth. The server is a linked device that your agent talks to.
Two usage methods
Use it at whatsapp.finereli.com for free or run your own copy on Cloudflare.
Built by @finereli
The project is open source with issues for questions and bug reports.
Hosted version
Sign in with Google, scan QR code, and add https://whatsapp.finereli.com/mcp to your agent.
Self-hosted version
Run on Cloudflare with git clone, npm install, and deploy with npm run deploy.
Encryption details
Messages encrypted at rest with PBKDF2-SHA256 and AES-256-GCM.
What it guarantees
It only reads messages. No tools send, edit, or delete anything in WhatsApp.
Data key security
Each account has a random data key encrypted with a password or Google login.
Phone numbers in chats
Phone numbers are replaced by keyed hashes in the database for privacy.
Search capabilities
Exact word search with no stemming or fuzzy matching.
Relinking process
Relink to reset history without losing stored messages.
Running for others
Set OPEN_SIGNUP=true to run as a service for multiple users.
Costs for self-hosted
Cloudflare Workers Paid plan costs $5 per account, with $0.20 per GB storage.
Known gaps
Chats with no names show as phone numbers and require agent intervention.
What happens next
Users can delete all data or relink to reset history without losing messages.
The short version
A free open-source tool lets AI agents search encrypted WhatsApp messages without sending or editing them.
