WhatsApp Chat Reader MCP server
✓ VerifiedAllows an AI client to summarize, search, and reason over local WhatsApp chat history by reading the local SQLite database.
Also known as NabheetCloud/wa-chat-reader, wa-chat-reader
- Stars
- 1
- Tools
- 2
- Downloads, 30 days
- 132
- Latest version
- 0.1.0
- Last commit
- Jul 5, 2026
- License
- MIT
What is WhatsApp Chat Reader MCP?
WhatsApp Chat Reader allows an AI client to summarize, search, and reason over local WhatsApp chat history by reading the local SQLite database. It exposes 2 tools, such as get_whatsapp_messages, get_whatsapp_chat_list.
Summary generated from the project's README
About WhatsApp Chat Reader MCP server
Summarizing and searching through your private WhatsApp conversations from within an AI client is what this tool enables. It works by reading the local ChatStorage.sqlite database used by the WhatsApp desktop application on macOS, Windows, or Linux. Because the server runs entirely on your machine without network code, your message data stays local and is only shared with the specific MCP client you choose to use.
Developers can connect this server to clients like Claude Desktop or Claude Code using Python and uv. The server provides two specific tools: get_whatsapp_messages for retrieving text from personal or group chats, and get_whatsapp_chat_list for viewing active chat names. To protect privacy and performance, the WHATSAPP_MAX_DAYS environment variable limits how far back the AI can look, defaulting to a 30-day window. Users on macOS must grant Full Disk Access to the process to reach the protected database container.
What you can do with it
- 1Summarize recent group activityAsk your AI client to provide a summary of messages from specific group chats over the last few days.
- 2Identify active conversationsRequest a list of all the WhatsApp chats you have participated in during the current week.
- 3Analyze messaging patternsGenerate an offline HTML dashboard to visualize your messaging volume and daily rhythms.
Written from the project's README. Every use case is checked against a quote from it.
How to install WhatsApp Chat Reader MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall WhatsApp Chat Reader MCP in Claude Code
$ claude mcp add wa-chat-reader -- uvx wa-chat-readerInstall WhatsApp Chat Reader MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"wa-chat-reader": {
"command": "uvx",
"args": [
"wa-chat-reader"
]
}
}
}Install WhatsApp Chat Reader MCP in VS Code
.vscode/mcp.json
{
"servers": {
"wa-chat-reader": {
"type": "stdio",
"command": "uvx",
"args": [
"wa-chat-reader"
]
}
}
}Install WhatsApp Chat Reader MCP in VS Code CLI
$ code --add-mcp '{"name":"wa-chat-reader","type":"stdio","command":"uvx","args":["wa-chat-reader"]}'Install WhatsApp Chat Reader MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"wa-chat-reader": {
"command": "uvx",
"args": [
"wa-chat-reader"
]
}
}
}Install WhatsApp Chat Reader MCP in Codex
$ codex mcp add wa-chat-reader -- uvx wa-chat-readerInstall WhatsApp Chat Reader MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.wa-chat-reader] command = "uvx" args = ["wa-chat-reader"]
Install WhatsApp Chat Reader MCP in Gemini CLI
$ gemini mcp add -s user wa-chat-reader uvx -- wa-chat-readerInstall WhatsApp Chat Reader MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"wa-chat-reader": {
"command": "uvx",
"args": [
"wa-chat-reader"
]
}
}
}WhatsApp Chat Reader MCP tools 2
Detected from the READMEget_whatsapp_messagesget_whatsapp_chat_list
| get_whatsapp_messages | — | |
| get_whatsapp_chat_list | — |
Configuration
WHATSAPP_BACKUP_PATHSSemicolon-separated fallback database paths, tried after the primary paths.
WHATSAPP_DB_PATHSSemicolon-separated paths to ChatStorage.sqlite. If unset, a platform default is used.
WHATSAPP_DEBUGSet to 'true' for verbose logging to stderr.
WHATSAPP_LOG_FILEOptional path to also write logs to a file.
WHATSAPP_MAX_DAYSMaximum look-back window in days a caller may request.
| Name | Description | |
|---|---|---|
| WHATSAPP_BACKUP_PATHS | Semicolon-separated fallback database paths, tried after the primary paths. | |
| WHATSAPP_DB_PATHS | Semicolon-separated paths to ChatStorage.sqlite. If unset, a platform default is used. | |
| WHATSAPP_DEBUG | Set to 'true' for verbose logging to stderr. | |
| WHATSAPP_LOG_FILE | Optional path to also write logs to a file. | |
| WHATSAPP_MAX_DAYS | Maximum look-back window in days a caller may request. |
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablenabheetcloud/wa-chat-reader is public and reachablegithub.com/nabheetcloud/wa-chat-reader ↗Pass
- Package names this repository as its sourcewa-chat-reader names nabheetcloud/wa-chat-reader as sourcepypi.org/project/wa-chat-reader/ ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-07-05github.com/nabheetcloud/wa-chat-reader ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from wa-chat-readerPass
- No critical advisory in the package or its dependencies29 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model2 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubwa-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
WhatsApp Chat Reader MCP questions
How do I add WhatsApp Chat Reader MCP to Claude Code?
Run claude mcp add wa-chat-reader -- uvx wa-chat-reader in your terminal. Add --scope user to make it available in every project.
How do I add WhatsApp Chat Reader MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does WhatsApp Chat Reader MCP provide?
It exposes 2 tools, including get_whatsapp_messages, get_whatsapp_chat_list.
Is my WhatsApp data sent to the cloud?
No, everything runs locally and no data ever leaves your computer.
Can this server modify or delete my messages?
No, the server is read-only and uses SQLite mode that prevents writing, modifying, or deleting anything.
What permissions are needed on macOS to use this?
The process requires Full Disk Access in your System Settings because the WhatsApp database is in a protected group container.
How far back can the AI read my messages?
The look-back window is capped by the WHATSAPP_MAX_DAYS variable, which defaults to 30 days.