{
  "markdown": "# wa-chat-reader\n\n<!-- mcp-name: io.github.NabheetCloud/wa-chat-reader -->\n\n**Unofficial, read-only [MCP](https://modelcontextprotocol.io) server for your local WhatsApp chat history.**\n\n`wa-chat-reader` reads the WhatsApp `ChatStorage.sqlite` database that the WhatsApp\ndesktop app keeps on your machine and exposes two tools to any MCP client (Claude\nCode, Claude Desktop, etc.) so you can summarize, search, and reason over your own\nmessages. Everything runs locally — **no data ever leaves your computer.**\n\n> ⚠️ **Not affiliated with, endorsed by, or connected to WhatsApp or Meta.**\n> \"WhatsApp\" is a trademark of Meta Platforms, Inc. This is an independent,\n> unofficial tool that only reads a database WhatsApp already stores on your device.\n\n---\n\n## Privacy & security\n\nThis tool touches highly sensitive data — your private conversations. Read this first.\n\n- **Read-only.** The database is opened with SQLite `mode=ro&immutable=1`; the server\n  never writes to, modifies, or deletes anything.\n- **Local-only.** There is no network code. Messages are returned to your MCP client\n  and nowhere else. Whatever LLM/client you connect will, of course, see the message\n  text you ask it to read — you control that by choosing which client to run.\n- **Your consent, your data.** Only run this against your own device and your own\n  chats. Do not use it to access anyone else's messages.\n- **macOS access.** The WhatsApp database lives in a protected group container. The\n  process running this server needs **Full Disk Access**\n  (System Settings → Privacy & Security → Full Disk Access), or point\n  `WHATSAPP_DB_PATHS` at a readable copy you export yourself.\n- **Scope control.** `WHATSAPP_MAX_DAYS` (default 30) caps how far back any single\n  call can read.\n\n---\n\n## Install\n\nRequires Python ≥ 3.10. Recommended: [`uv`](https://docs.astral.sh/uv/) so the server\nruns in an isolated environment.\n\n```bash\n# one-shot run (no install)\nuvx wa-chat-reader\n\n# or install with pip\npip install wa-chat-reader\nwa-chat-reader\n```\n\n## Use in Claude Code\n\n```bash\nclaude mcp add wa-chat-reader -- uvx wa-chat-reader\n```\n\nOr install as a plugin (see the marketplace section below), then ask Claude things like:\n\n- \"Summarize my unread WhatsApp group chats from the last 3 days.\"\n- \"List the WhatsApp chats I've been active in this week.\"\n\n## Configuration\n\nAll configuration is via environment variables (all optional):\n\n| Variable | Default | Description |\n|---|---|---|\n| `WHATSAPP_DB_PATHS` | platform default | `;`-separated candidate paths to `ChatStorage.sqlite` (first readable wins) |\n| `WHATSAPP_BACKUP_PATHS` | — | `;`-separated fallback paths, tried after the primary paths |\n| `WHATSAPP_MAX_DAYS` | `30` | Max look-back window (days) a caller may request |\n| `WHATSAPP_DEBUG` | `false` | `true` for verbose logging to stderr |\n| `WHATSAPP_LOG_FILE` | — | Optional path to also write logs to a file |\n\nDefault database locations:\n\n| OS | Path |\n|---|---|\n| macOS | `~/Library/Group Containers/group.net.whatsapp.WhatsApp.shared/ChatStorage.sqlite` |\n| Windows | `~/AppData/Roaming/WhatsApp/Databases/ChatStorage.sqlite` |\n| Linux | `~/.local/share/whatsapp/ChatStorage.sqlite` |\n\n## Tools\n\n| Tool | Description |\n|---|---|\n| `get_whatsapp_messages` | Concatenated message text from group and personal chats within a look-back window. Params: `days` (1–max), `chat_type` (`all`/`groups`/`personal`). Read-only. |\n| `get_whatsapp_chat_list` | Active chat names (no message bodies) within a look-back window. Param: `days`. Read-only. |\n\nBoth tools are annotated `readOnlyHint: true`.\n\n## Bonus: activity dashboard\n\n`whatsapp_dashboard.py` renders a self-contained, offline HTML dashboard of your\nmessaging activity (volume over time, daily/weekly rhythm, top chats) straight from\nthe same database:\n\n```bash\npython3 whatsapp_dashboard.py            # -> whatsapp_dashboard.html\n```\n\nThe generated HTML contains real contact names — it is git-ignored and meant to stay\nlocal.\n\n## Develop\n\n```bash\ngit clone https://github.com/NabheetCloud/wa-chat-reader\ncd wa-chat-reader\npip install -e .\npython3 simple_whatsapp_mcp.py           # run from source without installing\n```\n\n## License\n\n[MIT](./LICENSE) © 2026 Nabheet Madan\n",
  "bytes": 4222,
  "sha": "a85f6a3132fe790719b4e8f0b2919e87bff91a36298872ce0387331d8ff42711",
  "repo_slug": "nabheetcloud/wa-chat-reader",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_nabheetcloud_wa_chat_reader_e891aae8/readme"
}