mcpField
W
WhatsApp Chat Reader (Unofficial)

WhatsApp Chat Reader (Unofficial)

本地服务
github.com/NabheetCloud通信协作117 周前更新
代码仓库

关于 WhatsApp Chat Reader (Unofficial)

WhatsApp Chat Reader (Unofficial) 是读取本机 WhatsApp 桌面应用聊天数据库的只读工具，适合需要查询和分析个人聊天记录的用户。数据留在本机，并通过 MCP 客户端提供消息和活跃聊天列表。

主要功能

  1. 01只读访问本机聊天数据库
  2. 02按时间范围获取消息文本
  3. 03按群组或个人聊天筛选
  4. 04列出活跃聊天名称
  5. 05生成离线活动仪表板

适用场景

  1. 01汇总近期群聊消息
  2. 02查找一段时间内活跃的聊天
  3. 03查看消息活动的时间变化

MCP 相关

作为 MCP 服务，提供读取消息文本和获取活跃聊天列表的两个只读工具；数据仅返回给本地 MCP 客户端。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
  "mcpServers": {
    "nabheetcloud-wa-chat-reader": {
      "command": "uvx",
      "args": [
        "wa-chat-reader"
      ],
      "env": {
        "WHATSAPP_DB_PATHS": "<WHATSAPP_DB_PATHS>",
        "WHATSAPP_BACKUP_PATHS": "<WHATSAPP_BACKUP_PATHS>",
        "WHATSAPP_MAX_DAYS": "<WHATSAPP_MAX_DAYS>",
        "WHATSAPP_DEBUG": "<WHATSAPP_DEBUG>",
        "WHATSAPP_LOG_FILE": "<WHATSAPP_LOG_FILE>"
      }
    }
  }
}
启动命令uvx wa-chat-reader
需要配置的环境变量
WHATSAPP_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.

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包
pypiwa-chat-reader0.1.0

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

wa-chat-reader

面向本地 WhatsApp 聊天记录的非官方、只读 MCP 服务。

wa-chat-reader 会读取 WhatsApp 桌面应用保存在你设备上的 WhatsApp ChatStorage.sqlite 数据库，并向任何 MCP 客户端（Claude Code、Claude Desktop 等）提供两个工具，让你总结、搜索并分析自己的消息。所有操作都在本地进行——数据绝不会离开你的电脑。

⚠️ 与 WhatsApp 或 Meta 无任何关联、背书或联系。 “WhatsApp” 是 Meta Platforms, Inc. 的商标。这是一款独立的非官方工具，只读取 WhatsApp 已保存在你设备上的数据库。

隐私与安全

此工具会接触高度敏感的数据——你的私人对话。请先阅读此部分。

  • 只读。 数据库以 SQLite mode=ro&immutable=1 模式打开；服务绝不会写入、修改或删除任何内容。
  • 仅限本地。 此工具不包含任何网络代码。消息只会返回给你的 MCP 客户端，不会发送到其他地方。当然，你连接的任何大模型/客户端都会看到你要求它读取的消息文本——你可以通过选择要运行的客户端来控制这一点。
  • 你的同意，你的数据。 仅对你自己的设备和聊天记录运行此工具。请勿用它访问他人的消息。
  • macOS 访问权限。 WhatsApp 数据库位于受保护的群组容器中。运行此服务的进程需要完全磁盘访问权限（系统设置 → 隐私与安全性 → 完全磁盘访问权限），或者将 WHATSAPP_DB_PATHS 指向你自行导出且可读取的副本。
  • 范围控制。 WHATSAPP_MAX_DAYS（默认值为 30）会限制单次调用可读取的历史天数。

安装

需要 Python ≥ 3.10。建议使用 uv，让服务在隔离环境中运行。

# one-shot run (no install)
uvx wa-chat-reader

# or install with pip
pip install wa-chat-reader
wa-chat-reader

在 Claude Code 中使用

claude mcp add wa-chat-reader -- uvx wa-chat-reader

或者将其安装为插件（请参阅下方的市场版块），然后向 Claude 提出以下问题：

  • “总结过去 3 天中我尚未读过的 WhatsApp 群聊。”
  • “列出本周我活跃过的 WhatsApp 聊天。”

配置

所有配置都通过环境变量完成（均为可选）：

变量默认值说明
WHATSAPP_DB_PATHS平台默认路径以 ; 分隔的 ChatStorage.sqlite 候选路径（使用第一个可读取的路径）
WHATSAPP_BACKUP_PATHS—以 ; 分隔的备用路径，在主要路径之后尝试
WHATSAPP_MAX_DAYS30调用方可请求的最大回溯天数
WHATSAPP_DEBUGfalse设为 true 可将详细日志输出到 stderr
WHATSAPP_LOG_FILE—可选路径，也可将日志写入文件

默认数据库位置：

操作系统路径
macOS~/Library/Group Containers/group.net.whatsapp.WhatsApp.shared/ChatStorage.sqlite
Windows~/AppData/Roaming/WhatsApp/Databases/ChatStorage.sqlite
Linux~/.local/share/whatsapp/ChatStorage.sqlite

工具

工具说明
get_whatsapp_messages在回溯时间范围内，拼接群聊和个人聊天中的消息文本。参数：days（1–最大值）、chat_type（all/groups/personal）。只读。
get_whatsapp_chat_list在回溯时间范围内列出活跃聊天名称（不包含消息正文）。参数：days。只读。

两个工具都标注了 readOnlyHint: true。

附加功能：活动仪表板

whatsapp_dashboard.py 可直接从同一数据库生成一个独立的离线 HTML 仪表板，展示你的消息活动（随时间变化的消息量、每日/每周节奏、热门聊天）：

python3 whatsapp_dashboard.py            # -> whatsapp_dashboard.html

生成的 HTML 包含真实联系人姓名——该文件已加入 git 忽略规则，应该保留在本地。

开发

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

许可证

MIT © 2026 Nabheet Madan

评论

支持 Markdown

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。