WhatsApp Chat Reader (Unofficial)

io.github.NabheetCloudPublished by GitHub account NabheetCloudv0.1.0Updated Oct 24, 2026

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

VerifiedSTDIODesktop onlyFiles & StorageCommunication & Collaboration

Overview

AI-generated overview

Read-only local MCP server that lets an assistant search and summarize your own WhatsApp desktop chat history.

What you can do
Reads the ChatStorage.sqlite database kept by the WhatsApp desktop app and exposes two read-only tools. get_whatsapp_messages returns concatenated message text from group and personal chats within a look-back window, with days and chat_type parameters. get_whatsapp_chat_list returns active chat names without message bodies. A separate script can render an offline HTML activity dashboard from the same database.
When to use it
Use it when you want an assistant to summarize, search, or reason over your own WhatsApp conversations on the same machine, for example summarizing recent group chats or listing chats you were active in this week. It is not for accessing anyone else's messages or for sending anything.
Requirements
Local process on a desktop machine, run with uvx or pip; Python 3.10 or newer. On macOS the process needs Full Disk Access, or WHATSAPP_DB_PATHS must point at a readable copy. Optional environment variables: WHATSAPP_DB_PATHS, WHATSAPP_BACKUP_PATHS, WHATSAPP_MAX_DAYS, WHATSAPP_DEBUG, WHATSAPP_LOG_FILE. No network access or account credentials.
Before you install
It reads private conversations, and whatever message text you ask for is passed to the MCP client or LLM you connect, so choose that client deliberately. Only run it against your own device and chats. The database is opened read-only and the server has no network code, but the optional dashboard HTML contains real contact names and should stay local. WHATSAPP_MAX_DAYS caps how far back a call may read.

Installation

In SourceWeft

  1. Open WhatsApp Chat Reader (Unofficial) in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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.

bash
# one-shot run (no install)uvx wa-chat-reader
# or install with pippip install wa-chat-readerwa-chat-reader

Use in Claude Code

bash
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:

bash
python3 whatsapp_dashboard.py            # -> whatsapp_dashboard.html

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

Develop

bash
git clone https://github.com/NabheetCloud/wa-chat-readercd wa-chat-readerpip install -e .python3 simple_whatsapp_mcp.py           # run from source without installing

License

MIT © 2026 Nabheet Madan

Source: README.md at commit fadfafb

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.0LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts