feat(whatsapp): MCP tool for searching WhatsApp conversations

[williamjameshandley]

Summary

Add an MCP tool for reading and searching WhatsApp message history, leveraging a rooted Android phone's direct database access.

Background Research

WhatsApp stores all messages in an unencrypted SQLite database on Android:

• Messages: /data/data/com.whatsapp/databases/msgstore.db
• Contacts: /data/data/com.whatsapp/databases/wa.db

With root access, these can be read directly — no linked device slot consumed, no reverse-engineered protocol needed, complete history available.

Key tables in msgstore.db

• message — text_data, timestamp, key_remote_jid (contact/group), media paths, read receipts, message_type
• chat — chat metadata, group info
• Media referenced by path in the message table

Approach: Direct SQLite access (rooted phone)

Advantages over the whatsmeow-based MCP servers (lharries/whatsapp-mcp):

• No linked device slot consumed (limit: 4 for personal accounts)
• Complete message history (not just messages received after linking)
• No WebSocket connection to WhatsApp servers (zero risk of account restrictions)
• Simpler stack — no Go bridge, no binary protocol parsing, just SQL queries
• Real-time — WhatsApp writes to DB live

Sync options:

1. Periodic adb pull or on-device script copying msgstore.db to the machine
2. Direct access via SSH/Termux with root on the phone over local network
3. Could also index with mcp-llm-embeddings for semantic search

Existing WhatsApp MCP servers (for reference)

• lharries/whatsapp-mcp — Python+Go, uses whatsmeow (WhatsApp Web multi-device protocol), stores in SQLite, full send/receive
• kotevcode/whatsapp-mcp — full-text search across messages, group filtering

Proposed Tool Design

Single mcp-whatsapp tool with operations:

• search_messages — full-text search across all chats, with optional contact/group filter and date range
• get_chat_history — retrieve messages from a specific chat with pagination
• list_chats — list all chats with metadata (last message, message count)
• search_contacts — search contacts by name or number

Backed by SQL queries against a local copy of msgstore.db. Could also integrate with mcp-llm-embeddings for semantic search.

Prerequisites

• Rooted Android phone (for direct database access)
• Sync mechanism (adb pull / SSH / Termux)

References

• WhatsApp database forensics: https://www.magnetforensics.com/blog/artifact-profile-whatsapp-messenger/
• msgstore.db schema: https://github.com/andreas-mausch/whatsapp-viewer/blob/master/data/msgstore.db.schema.sql
• WhatsApp-Chat-Exporter (parses crypt12/14/15): https://github.com/KnugiHK/WhatsApp-Chat-Exporter
• whatsmeow library: https://github.com/tulir/whatsmeow