Skip to main content
Glama
WhatsApp Groups MCP

WhatsApp Groups MCP

by mlteam-ai

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

whatsapp-chats

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.

whatsapp-chats server

The MCP server Claude starts. Four read-only tools: list_chats, search_messages, get_messages, get_document. Opens the database read-only and checks chats.txt on every call.

whatsapp-chats folder

Prints your data folder, which holds chats.txt and data/.

Your data folder is:

  • Windows: %LOCALAPPDATA%\MLTeam WhatsApp Chats

  • macOS: ~/Library/Application Support/MLTeam WhatsApp Chats

  • Linux: ~/.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").

  1. 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 | sh

    Then close the terminal and open a new one.

  2. Install this tool:

    uv tool install git+https://github.com/mlteam-ai/mlteam-whatsapp-chats-mcp
  3. Optional, 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.txt in your data folder (see above; whatsapp-chats folder prints it) with one chat per line: the exact name of a group or contact (for example Family Trip), or its ID. For direct chats an ID such as 905551234567@s.whatsapp.net is 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.

  4. Start the bridge, link your WhatsApp, and leave the window open:

    whatsapp-chats

    Scan 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-chats again after a restart.

    Optional, once linked: whatsapp-chats --list prints your groups and contacts with their IDs (120363012345678901@g.us, 905551234567@s.whatsapp.net). IDs keep working if a name changes.

  5. Connect it to Claude, once.

    Claude Code:

    claude mcp add -s user whatsapp-chats -- whatsapp-chats server

    Claude 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) or which whatsapp-chats (macOS) and put that in "command" (on Windows, write \\ for each \).

  6. 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-mcp

Then 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.txt and restart the bridge. Its earlier messages are not backfilled. To get them, start over: remove the device in WhatsApp > Linked devices, delete data/ in your data folder, and run whatsapp-chats again.

  • 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.db is 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-check

The 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 tools
get_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

    A3.5/5.0

    Scored across 3 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    All three tools follow a clean verb_noun snake_case pattern (list_groups, search_messages, get_messages), making purpose predictable from name alone.

    Tool Count4/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Connects WhatsApp group chats to Claude, enabling reading, searching, exporting, replying, and AI-powered intelligence processing of conversations.
      16
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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.
      7
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides 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 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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