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 分