Skip to main content
Glama
NabheetCloud

wa-chat-reader

by NabheetCloud
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

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.

Related MCP server: WhatsApp MCP Server (TypeScript)

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

No tool schema history has been recorded yet.

This server cannot be installed

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Maintenance

ActivitySlowing
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

  • chatflow
    io.github.Yersat

    WhatsApp CRM for AI agents: search contacts, read chats, manage the sales pipeline, send messages.

    CRMCommunication
    2
  • WaAPIOAuth
    app.waapi

    Messaging tools for AI agents: send messages, manage chats, groups and channels.

    1
  • Carbon VoiceOAuth
    app.carbonvoice.mcp

    Carbon Voice MCP serves as a bridge that connects AI assistants like ChatGPT, Claude, and Cursor to a user's Carbon Voice account, turning voice messages and conversations into a private, on-demand knowledge base. It provides 28 specialized tools for comprehensive voice messaging management, including creating and sending messages, accessing conversation history with instant transcription, running AI actions (summarization, TLDR generation, meeting notes), and managing workspace collaboration through folders, contacts, and team communications.

    CommunicationKnowledge & MemoryText Summarization
    2
  • LLMemoryOAuth
    io.github.meir-may

    Search your AI chat history (ChatGPT, Claude, Codex) from any MCP client. Remote, private, read-only

    SearchKnowledge & Memory
    2

Related MCP Servers

  • WhatsApp MCP Server

    Joshnaacsha
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI agents to interact with your personal WhatsApp account, allowing them to search messages and contacts, retrieve chat history, and send messages to individuals or groups. Uses WhatsApp Web API with local data storage for privacy and security.
    13
    ISC

  • WhatsApp MCP Server

    aukik
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI agents to interact with your personal WhatsApp account to search messages, list chats, and send messages. It stores all authentication and message data locally using SQLite for privacy and direct multi-device API connection.
    13
    1
    ISC

  • duggai-messages

    duggsha
    A
    license
    Not graded
    quality
    C
    maintenance
    Local-first WhatsApp and iMessage memory for AI coding agents. It provides MCP tools to search messages, get recent context, summarize relationships, draft replies, and view unreplied threads.
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/NabheetCloud/wa-chat-reader'

If you have feedback or need assistance with the MCP directory API, please join our Discord server