English Français العربية

WhatsApp Chat Reader (Unofficial)

السجل الرسمي أخرى

Unofficial read-only MCP server for your local WhatsApp chat history (stays on your machine).

الشيفرة المصدرية التوثيق

التثبيت

أضف هذا إلى إعدادات MCP في عميلك (Claude Desktop: claude_desktop_config.json، وCursor: ‏.cursor/mcp.json، ويستخدم VS Code وغيره الصيغة نفسها «mcpServers»).

PYPI package wa-chat-reader
Claude Code 
claude mcp add whatsapp-chat-reader-unofficial -e 'WHATSAPP_DB_PATHS=<WHATSAPP_DB_PATHS>' -e 'WHATSAPP_BACKUP_PATHS=<WHATSAPP_BACKUP_PATHS>' -e 'WHATSAPP_MAX_DAYS=30' -e 'WHATSAPP_DEBUG=false' -e 'WHATSAPP_LOG_FILE=<WHATSAPP_LOG_FILE>' -- uvx wa-chat-reader==0.1.0
إعداد JSON (Claude Desktop وCursor وVS Code) 
{
    "mcpServers": {
        "whatsapp-chat-reader-unofficial": {
            "command": "uvx",
            "args": [
                "wa-chat-reader==0.1.0"
            ],
            "env": {
                "WHATSAPP_DB_PATHS": "<WHATSAPP_DB_PATHS>",
                "WHATSAPP_BACKUP_PATHS": "<WHATSAPP_BACKUP_PATHS>",
                "WHATSAPP_MAX_DAYS": "30",
                "WHATSAPP_DEBUG": "false",
                "WHATSAPP_LOG_FILE": "<WHATSAPP_LOG_FILE>"
            }
        }
    }
}

متغيرات البيئة

  • WHATSAPP_DB_PATHS Semicolon-separated paths to ChatStorage.sqlite. If unset, a platform default is used.
  • WHATSAPP_BACKUP_PATHS Semicolon-separated fallback database paths, tried after the primary paths.
  • WHATSAPP_MAX_DAYS Maximum look-back window in days a caller may request.
  • WHATSAPP_DEBUG Set to 'true' for verbose logging to stderr.
  • WHATSAPP_LOG_FILE Optional path to also write logs to a file.

التوثيق

مأخوذ من ملف README للمشروع على GitHub ويُحدَّث أسبوعيًا. تفتح الروابط على GitHub.

المحتويات
  1. wa-chat-reader
  2. Privacy & security
  3. Install
  4. Use in Claude Code
  5. Configuration
  6. Tools
  7. Bonus: activity dashboard
  8. Develop
  9. License

wa-chat-reader

Unofficial, read-only MCP server for your local WhatsApp chat history.

wa-chat-reader reads the WhatsApp ChatStorage.sqlite database that the WhatsApp desktop app keeps on your machine and exposes two tools to any MCP client (Claude Code, Claude Desktop, etc.) so you can summarize, search, and reason over your own messages. Everything runs locally — no data ever leaves your computer.

⚠️ Not affiliated with, endorsed by, or connected to WhatsApp or Meta. "WhatsApp" is a trademark of Meta Platforms, Inc. This is an independent, unofficial tool that only reads a database WhatsApp already stores on your device.

Privacy & security

This tool touches highly sensitive data — your private conversations. Read this first.

  • Read-only. The database is opened with SQLite mode=ro&immutable=1; the server never writes to, modifies, or deletes anything.
  • Local-only. There is no network code. Messages are returned to your MCP client and nowhere else. Whatever LLM/client you connect will, of course, see the message text you ask it to read — you control that by choosing which client to run.
  • Your consent, your data. Only run this against your own device and your own chats. Do not use it to access anyone else's messages.
  • macOS access. The WhatsApp database lives in a protected group container. The process running this server needs Full Disk Access (System Settings → Privacy & Security → Full Disk Access), or point WHATSAPP_DB_PATHS at a readable copy you export yourself.
  • Scope control. WHATSAPP_MAX_DAYS (default 30) caps how far back any single call can read.

Install

Requires Python ≥ 3.10. Recommended: uv so the server runs in an isolated environment.

# one-shot run (no install)
uvx wa-chat-reader

# or install with pip
pip install wa-chat-reader
wa-chat-reader

Use in Claude Code

claude mcp add wa-chat-reader -- uvx wa-chat-reader

Or install as a plugin (see the marketplace section below), then ask Claude things like:

  • "Summarize my unread WhatsApp group chats from the last 3 days."
  • "List the WhatsApp chats I've been active in this week."

Configuration

All configuration is via environment variables (all optional):

VariableDefaultDescription
WHATSAPP_DB_PATHSplatform default;-separated candidate paths to ChatStorage.sqlite (first readable wins)
WHATSAPP_BACKUP_PATHS—;-separated fallback paths, tried after the primary paths
WHATSAPP_MAX_DAYS30Max look-back window (days) a caller may request
WHATSAPP_DEBUGfalsetrue for verbose logging to stderr
WHATSAPP_LOG_FILE—Optional path to also write logs to a file

Default database locations:

OSPath
macOS~/Library/Group Containers/group.net.whatsapp.WhatsApp.shared/ChatStorage.sqlite
Windows~/AppData/Roaming/WhatsApp/Databases/ChatStorage.sqlite
Linux~/.local/share/whatsapp/ChatStorage.sqlite

Tools

ToolDescription
get_whatsapp_messagesConcatenated message text from group and personal chats within a look-back window. Params: days (1–max), chat_type (all/groups/personal). Read-only.
get_whatsapp_chat_listActive chat names (no message bodies) within a look-back window. Param: days. Read-only.

Both tools are annotated readOnlyHint: true.

Bonus: activity dashboard

whatsapp_dashboard.py renders a self-contained, offline HTML dashboard of your messaging activity (volume over time, daily/weekly rhythm, top chats) straight from the same database:

python3 whatsapp_dashboard.py            # -> whatsapp_dashboard.html

The generated HTML contains real contact names — it is git-ignored and meant to stay local.

Develop

git clone https://github.com/NabheetCloud/wa-chat-reader
cd wa-chat-reader
pip install -e .
python3 simple_whatsapp_mcp.py           # run from source without installing

License

MIT © 2026 Nabheet Madan

الأسئلة الشائعة

ما هو WhatsApp Chat Reader (Unofficial)؟

Unofficial read-only MCP server for your local WhatsApp chat history (stays on your machine).

كيف أثبّت WhatsApp Chat Reader (Unofficial)؟

يعمل على جهازك. في Claude Code: claude mcp add whatsapp-chat-reader-unofficial -e 'WHATSAPP_DB_PATHS=<WHATSAPP_DB_PATHS>' -e 'WHATSAPP_BACKUP_PATHS=<WHATSAPP_BACKUP_PATHS>' -e 'WHATSAPP_MAX_DAYS=30' -e 'WHATSAPP_DEBUG=false' -e 'WHATSAPP_LOG_FILE=<WHATSAPP_LOG_FILE>' -- uvx wa-chat-reader==0.1.0. وفي العملاء الآخرين، الصق إعداد JSON من هذه الصفحة في إعدادات MCP الخاصة بهم.

هل يحتاج WhatsApp Chat Reader (Unofficial) إلى مفتاح API؟

لا يذكر إدراجه في السجل أي مفتاح أو سر إلزامي. قد تتطلب بعض الميزات حسابًا لدى الخدمة التي يتصل بها.

هل WhatsApp Chat Reader (Unofficial) مفتوح المصدر؟

نعم. شيفرته متاحة على GitHub بترخيص MIT.

من يصون WhatsApp Chat Reader (Unofficial)؟

ينشره NabheetCloud. يدرجه AI.tn لكنه لا يصونه ولا يوصي به.

من سجل MCP الرسمي. الإدراج ليس توصية: راجع شيفرة الخادم وصلاحياته قبل منحه الوصول إلى بياناتك.