wa-chat-reader
Reads local WhatsApp chat history to enable search, summarization, and analysis of messages through MCP tools.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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_PATHSat a readable copy you export yourself.Scope control.
WHATSAPP_MAX_DAYS(default 30) caps how far back any single call can read.
Related MCP server: WhatsApp MCP Server
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-readerUse in Claude Code
claude mcp add wa-chat-reader -- uvx wa-chat-readerOr 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 |
| platform default |
|
| — |
|
|
| Max look-back window (days) a caller may request |
|
|
|
| — | Optional path to also write logs to a file |
Default database locations:
OS | Path |
macOS |
|
Windows |
|
Linux |
|
Tools
Tool | Description |
| Concatenated message text from group and personal chats within a look-back window. Params: |
| Active chat names (no message bodies) within a look-back window. Param: |
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.htmlThe 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 installingLicense
MIT © 2026 Nabheet Madan
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Your WhatsApp history in Claude and ChatGPT: search years of chats, voice notes transcribed.
Your own WhatsApp in Claude and ChatGPT: read chats, draft replies, send messages you approve.
Connect your own WhatsApp number to Cursor, Claude and ChatGPT: catch up, search, send replies.
Read, summarize and send your own WhatsApp messages from AI assistants (OAuth 2.1).
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to interact with your personal WhatsApp account, allowing them to search messages and contacts, retrieve chat history, and send messages to individuals or groups. Uses WhatsApp Web API with local data storage for privacy and security.ISC
- AlicenseNot gradedqualityCmaintenanceEnables LLM clients to read and search your own WhatsApp messages stored in a local SQLite database, captured live via a linked device.MIT
- AlicenseNot gradedqualityDmaintenanceEnables local querying of WhatsApp message history via SQLite, with profile separation, media transcription, and operational summaries.1MIT
- AlicenseNot gradedqualityBmaintenanceProvides Claude with read-only access to your WhatsApp chat history entirely on your local machine, enabling natural language search, summarization, and retrieval of messages without sending data to the cloud.14 npmMIT