WhatsApp Chat Reader (Unofficial)

io.github.NabheetCloud由 GitHub 账号 NabheetCloud 发布v0.1.0更新于 Oct 24, 2026

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

已验证STDIO仅桌面文件与存储沟通与协作

概览

AI 生成的概览

只读的本地 MCP 服务器，让助手搜索并总结你自己 WhatsApp 桌面版的聊天记录。

可以做什么
读取 WhatsApp 桌面应用保存在本机的 ChatStorage.sqlite 数据库，并提供两个只读工具。get_whatsapp_messages 返回指定回溯窗口内群聊和私聊的拼接消息文本，参数为 days 和 chat_type。get_whatsapp_chat_list 返回活跃聊天名称，不含消息正文。另有一个脚本可用同一数据库生成离线 HTML 活动看板。
适用场景
适合在同一台机器上让助手总结、搜索或分析你自己的 WhatsApp 对话，例如总结最近的群聊，或列出本周活跃的聊天。不适用于访问他人的消息，也不能发送任何内容。
运行要求
在桌面机器上以本地进程运行，可用 uvx 或 pip 启动，需要 Python 3.10 或更高版本。macOS 上该进程需要“完全磁盘访问权限”，或将 WHATSAPP_DB_PATHS 指向可读的副本。可选环境变量：WHATSAPP_DB_PATHS、WHATSAPP_BACKUP_PATHS、WHATSAPP_MAX_DAYS、WHATSAPP_DEBUG、WHATSAPP_LOG_FILE。无需网络访问或账号凭据。
安装前请注意
它会读取私密对话，而你要求读取的消息文本会传给你所连接的 MCP 客户端或大模型，因此请谨慎选择客户端。仅对自己的设备和自己的聊天使用。数据库以只读方式打开，服务器没有网络代码，但可选的看板 HTML 含真实联系人姓名，应保留在本地。WHATSAPP_MAX_DAYS 限制单次调用可回溯的范围。

安装

在 SourceWeft 中

  1. 打开 控制台中的 WhatsApp Chat Reader (Unofficial)，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

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

来源：README.md，提交 fadfafb

工具

0
SourceWeft 尚未在沙箱中启动过该软件包，因此其工具未知。

版本历史

1
  1. v0.1.0最新Sep 16, 2026

评分

已满足适用检查项的 50%

该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分

    请保持端点能够响应 MCP 握手；SourceWeft 每 30 天探测一次。

  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list，或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分