WhatsApp Groups MCP
Read-only access to permitted WhatsApp group chats (this schema exposes no direct-chat or document-reading tools).
List readable WhatsApp groups with message counts and date ranges.
Search message text case-insensitively across allowed groups, optionally limited to one group and filtered by ISO date, newest first.
Read a group's messages in time order, optionally since an ISO date, with a configurable limit.
It cannot send messages; all operations are read-only.
Provides read-only access to selected WhatsApp groups by linking a user's own WhatsApp account. Enables listing allowed groups, searching stored messages, and retrieving messages from those groups, while keeping data local.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@WhatsApp Groups MCP What did the Family Trip group decide about flights?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
WhatsApp chats MCP (read-only)
Let Claude answer questions from the WhatsApp chats you choose: groups and direct chats.
Your own account: each user links their own WhatsApp by scanning a QR code. No shared server and no shared credentials.
Your own chats: you list the chats (groups or contacts) Claude may read, by name or ID, in
chats.txt. Without that file, or with no chats in it, all your chats are read.Read-only: it cannot send messages, opens no network ports, and all data stays on your machine.
Not affiliated with WhatsApp or Meta. This uses an unofficial client (neonize / whatsmeow), which breaks WhatsApp's Terms of Service. Read-only use is low risk, but your account could be banned. Use at your own risk.
How it works
One command, whatsapp-chats, does three jobs:
Command | What it does |
| The bridge. Links to your WhatsApp as a device (like WhatsApp Web) and, while it runs, saves the text of messages and attached documents from your chosen chats. Messages from other chats are never stored. |
| The MCP server Claude starts. Four read-only tools: |
| Prints your data folder, which holds |
Your data folder is:
Windows:
%LOCALAPPDATA%\MLTeam WhatsApp ChatsmacOS:
~/Library/Application Support/MLTeam WhatsApp ChatsLinux:
~/.local/share/MLTeam WhatsApp Chats
Set WHATSAPP_CHATS_HOME to use another folder.
Related MCP server: WhatsApp MCP
Setup
Works on Windows, macOS and Linux. On Windows, type the commands in PowerShell (Start menu > "PowerShell").
Install uv, which installs Python and this tool for you.
Windows:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"macOS or Linux:
curl -LsSf https://astral.sh/uv/install.sh | shThen close the terminal and open a new one.
Install this tool:
uv tool install git+https://github.com/mlteam-ai/mlteam-whatsapp-chats-mcpOptional, before linking: choose which chats to read. Skip this to read all your chats: Claude then sees every group and direct chat. To choose, create
chats.txtin your data folder (see above;whatsapp-chats folderprints it) with one chat per line: the exact name of a group or contact (for exampleFamily Trip), or its ID. For direct chats an ID such as905551234567@s.whatsapp.netis more reliable, because contact names can take a while to sync. See chats.example.txt. WhatsApp sends past messages only once, at linking, and only chats chosen then are kept.Start the bridge, link your WhatsApp, and leave the window open:
whatsapp-chatsScan the QR code: WhatsApp on your phone > Settings > Linked devices > Link a device. It appears there as "MLTeam WhatsApp Chats Reader (read-only)". The bridge asks for up to one year of past messages. Your phone decides how much it sends, and it can take several minutes, so keep the bridge and your phone online meanwhile. After that, it stores new messages whenever it runs. Run
whatsapp-chatsagain after a restart.Optional, once linked:
whatsapp-chats --listprints your groups and contacts with their IDs (120363012345678901@g.us,905551234567@s.whatsapp.net). IDs keep working if a name changes.Connect it to Claude, once.
Claude Code:
claude mcp add -s user whatsapp-chats -- whatsapp-chats serverClaude Desktop: Settings > Developer > Edit Config, add this to
claude_desktop_config.json, then restart Claude Desktop:{ "mcpServers": { "whatsapp-chats": { "command": "whatsapp-chats", "args": ["server"] } } }If Claude Desktop cannot find the command, use its full path: run
where.exe whatsapp-chats(Windows) orwhich whatsapp-chats(macOS) and put that in"command"(on Windows, write\\for each\).Ask Claude, for example: "What did the Family Trip group decide about flights?"
Updating
uv tool install --force --upgrade git+https://github.com/mlteam-ai/mlteam-whatsapp-chats-mcpThen restart the bridge and Claude. This also updates the WhatsApp library, which fixes most
connection errors such as Client outdated (405).
Documents
The bridge downloads documents shared in your chats and keeps their text (not the files), so Claude can search and read them.
Supported: PDF, DOCX, XLSX, PPTX, and plain text (TXT, CSV, MD, JSON, TSV, LOG). Other types, files over 25 MB, and scanned PDFs (images, no text layer) are not read.
Old documents: WhatsApp deletes media from its servers after a while, so some documents from past history can no longer be downloaded. Claude sees these as "unreadable".
Already linked before this feature? Documents stored earlier have no text. Only new ones get it, unless you start over (see "Add a chat" below).
Changing chats
Add a chat: add a line to
chats.txtand restart the bridge. Its earlier messages are not backfilled. To get them, start over: remove the device in WhatsApp > Linked devices, deletedata/in your data folder, and runwhatsapp-chatsagain.Remove a chat: delete its line. Claude stops seeing it immediately. To delete its stored messages:
sqlite3 data/messages.db "DELETE FROM messages WHERE chat_jid='<chat JID>'"
Staying safe
Keep
data/private.data/session.dbis a logged-in WhatsApp session: anyone with it can act as your linked device. Never share or sync it (for example with OneDrive or iCloud). It is created owner-only.Revoke any time: WhatsApp > Settings > Linked devices > remove "MLTeam WhatsApp Chats Reader".
Untrusted files: documents come from other people. They are parsed in a separate process with a 120-second limit and never opened or run otherwise.
Prompt injection: anyone who messages you can write text aimed at Claude. These tools cannot send anything, but Claude's other tools (shell, web fetch) could leak data if Claude followed such text. Keep approving those tools yourself while using this server, or deny them.
Only include chats you are comfortable sending to Claude. Messages Claude reads go to Anthropic like the rest of your conversation.
If it stops connecting (for example
Client outdated (405)), update: see "Updating" above.
Development
git clone https://github.com/mlteam-ai/mlteam-whatsapp-chats-mcp.git
cd mlteam-whatsapp-chats-mcp
uv run whatsapp-chats # run the bridge from the checkout
uv run test_selfcheck.py # offline self-checkThe self-check feeds fake messages through the bridge and server without connecting to WhatsApp. CI runs it on Windows, macOS and Linux on every push.
Moving from an older checkout that kept data/ and chats.txt in the repo folder: move both into
your data folder (uv run whatsapp-chats folder). The bridge stops with this reminder until you do.
Report security issues privately: see SECURITY.md.
Available Tools
3 toolsget_messagesB
Read a group's messages in time order. since: ISO date; default returns the latest limit messages.
Inputs: group_jid (required), limit, since. Returns: result
list_groupsA
List the WhatsApp groups you may read, with message counts and date range.
Inputs: no named parameters. Returns: result
search_messagesB
Search message text (case-insensitive substring) in allowed groups.
group_jid: limit to one group. since: ISO date like 2026-11-01. Newest first.
Inputs: query (required), limit, since, group_jid. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
list_groups is clearly distinct, but search_messages and get_messages both return group message content and could be confused at a glance; the descriptions do clarify (text substring vs. time-ordered read), so boundaries are recoverable.
All three tools follow a clean verb_noun snake_case pattern (list_groups, search_messages, get_messages), making purpose predictable from name alone.
Three tools is minimal but well-matched to a deliberately narrow read-only scope; nothing is redundant, though the surface is close to feeling thin.
Core read workflows (discover groups, browse by time, search text) are covered, but there is no sender/author filtering, no message pagination/cursor controls, and no group metadata lookup; read-only may be intentional but leaves notable gaps for deeper queries.
Maintenance
Related MCP Connectors
Your own WhatsApp in Claude and ChatGPT: read chats, draft replies, send messages you approve.
Your WhatsApp history in Claude and ChatGPT: search years of chats, voice notes transcribed.
Connect your own WhatsApp number to Cursor, Claude and ChatGPT: catch up, search, send replies.
Ask questions across your WhatsApp inbox from Claude, ChatGPT, Cursor or any MCP client.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceConnects WhatsApp group chats to Claude, enabling reading, searching, exporting, replying, and AI-powered intelligence processing of conversations.16MIT
- AlicenseNot gradedqualityBmaintenanceEnables Claude to interact with WhatsApp: read chats, search messages, send messages with a mandatory confirmation step, and transcribe voice notes locally, all with encrypted storage and prompt-injection scrubbing.7MIT
- AlicenseNot gradedqualityBmaintenanceProvides Claude with read-only access to your WhatsApp chat history entirely on your local machine, enabling natural language search, summarization, and retrieval of messages without sending data to the cloud.14 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables Claude to read, search, and reply to your personal WhatsApp messages by linking as an extra device, with support for chat history, full-text search, media downloads, and sending messages or files.MIT