WhatsApp Chat Reader (Unofficial)
LocalAbout WhatsApp Chat Reader (Unofficial)
WhatsApp Chat Reader (Unofficial) is a read-only tool for accessing the local WhatsApp desktop chat database. It is for people who want to search or analyze their own chat history; data stays on the machine, and an MCP client can request messages or active chat names.
Key features
- 01Read-only access to the local chat database
- 02Retrieve message text within a time window
- 03Filter group or personal chats
- 04List active chat names
- 05Create an offline activity dashboard
Use cases
- 01Summarize recent group conversations
- 02Find chats active during a period
- 03Review messaging activity over time
MCP support
As an MCP server, it provides read-only tools for retrieving message text and listing active chats; data is returned only to the local MCP client.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
uvx wa-chat-readerWHATSAPP_DB_PATHSSemicolon-separated paths to ChatStorage.sqlite. If unset, a platform default is used.WHATSAPP_BACKUP_PATHSSemicolon-separated fallback database paths, tried after the primary paths.WHATSAPP_MAX_DAYSMaximum look-back window in days a caller may request.WHATSAPP_DEBUGSet to 'true' for verbose logging to stderr.WHATSAPP_LOG_FILEOptional path to also write logs to a file.Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.
Tools
Local servers expose tools only once running on your machine, and the maintainer has not provided a tool list.
Details
From the project READMEwa-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_PATHSat 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):
| Variable | Default | Description |
|---|---|---|
WHATSAPP_DB_PATHS | platform default | ;-separated candidate paths to ChatStorage.sqlite (first readable wins) |
WHATSAPP_BACKUP_PATHS | — | ;-separated fallback paths, tried after the primary paths |
WHATSAPP_MAX_DAYS | 30 | Max look-back window (days) a caller may request |
WHATSAPP_DEBUG | false | true for verbose logging to stderr |
WHATSAPP_LOG_FILE | — | Optional path to also write logs to a file |
Default database locations:
| OS | Path |
|---|---|
| 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
| Tool | Description |
|---|---|
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. |
get_whatsapp_chat_list | Active 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
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.