whatsapp-context

Let Claude, ChatGPT or any local AI assistant read the WhatsApp chats you choose. Read-only, on your Mac.

Español · Website · Security

What you can ask

• "Prioritise my WhatsApp from the last 24 hours. What needs a reply from me?"

• "Catch me up on the Kitchen renovation group since Monday."

• "Find the plumber's quote someone sent and summarise the thread around it."

The assistant suggests replies as text. You send them yourself: there is no send tool.

Related MCP server: whatsapp-mcp

How it works

WhatsApp for Mac ──▶ ChatStorage.sqlite (protected by macOS)
                          │ read-only
                  WAExport.app  ← the only program with Full Disk Access
                          │ export: index of every chat + text of allowed chats only
       MCP server + wa CLI (Python, no special permissions) ◀── config/policy.toml
                          │ stdio
          Claude Code · Claude Desktop · ChatGPT / Codex · any local MCP client

The export (~/.local/share/whatsapp-context) refreshes itself after 15 minutes or a policy change.

Install

Requirements:

• macOS 14 or later

• WhatsApp for Mac, signed in and synced

• Xcode Command Line Tools (xcode-select --install)

• uv (brew install uv); it installs Python 3.12 if needed

git clone https://github.com/AIOjPINEDA/whatsapp-context.git ~/whatsapp-context

cd ~/whatsapp-context

make setup

make setup checks requirements, installs /Applications/WAExport.app, creates config/policy.toml, opens System Settings so you switch on Full Disk Access for WAExport (only WAExport: never Terminal or an AI app) and offers to connect each assistant it finds. It is safe to run again. If your user cannot write to /Applications, it asks you to drag WAExport there in Finder.

macOS never lets an app ask for Full Disk Access, so that one switch is yours: drag WAExport from the Finder window that opens into the list and turn it on. The installer notices by itself and carries on. To do only this step again (after an update, say), run make grant.

Install with your AI agent

Paste this into Claude Code, Codex or any agent that can run commands on your Mac:

Clone https://github.com/AIOjPINEDA/whatsapp-context into ~/whatsapp-context and follow its INSTALL.md step by step. Ask me before every step that needs my action.

INSTALL.md is the agent's runbook. It stops for anything only you can do and never picks chats for you.

Choose what it can read

As shipped, the assistant reads no message text, only chat names, times and unread counts. Find exact names with uv run wa chats --all --grep kitchen (each chat shows its [JID]), then edit config/policy.toml:

[content]
chats = ["Book club", "+34 600 000 000"]   # exact names, phone numbers or JIDs
people = []                                # groups where this person is active

[projects."Kitchen renovation"]
context = "~/Documents/Kitchen"            # folder (its README.md) or file the assistant reads
chats = ["Kitchen renovation crew"]
patterns = ['^Kitchen ']                   # regex on chat names

[exclude]
chats = ["Family"]                         # never shown, not even as metadata

[options]
days = 180

• Precedence: exclude > chats > patterns > people. Case and extra spaces are ignored.

• A name shared by several chats grants nothing (unless they are one person's phone and linked ID): use the phone number or the JID.

• Check with uv run wa status: it lists Policy entry with no match and Policy conflict lines.

• Asking from the chat ("give access to the group X in project Y", "revoke X", "exclude X") writes only to config/policy-claude.toml, by JID with the name as a comment, and can never lift your exclusions. Revoke tells you if another rule still grants the chat.

• Search returns 50 results, most recent first, and says when it stopped; raise it with uv run wa search "quote" --limit 200.

Supported assistants

claude.ai and chatgpt.com in the browser need remote servers; this one is local on purpose.

Privacy & security

• Read-only. WAExport opens WhatsApp's database read-only, has no network and cannot send anything.

• Only allowed chats carry text. Everything else is metadata; the index never holds last-message text, drafts or media keys. [exclude] chats are hidden from every tool and wa view (their name stays in the local export index).

• Your assistant's provider receives whatever the assistant reads, like anything else you show it.

• The policy filters the MCP tools, not your account. An assistant with shell access runs as you and could read the export directly. Message text is untrusted: keep tool approvals on.

Threat model and reporting: SECURITY.md.

Update, uninstall, troubleshooting

Update: git pull in ~/whatsapp-context, then make setup and restart your assistants. If the CHANGELOG says WAExport changed, re-grant Full Disk Access (see below).

Uninstall: quit Claude Desktop, then make uninstall. It removes WAExport, the export and this repo's client entries; if an entry cannot be removed it says so, exits with an error and keeps WAExport and the export. Then remove WAExport from Full Disk Access and delete the folder.

FAQ

• Can it send messages? No, and it never will.

• Does it link a device or use the WhatsApp API? No. It reads what WhatsApp for Mac already stored.

• Windows, Linux, iPhone or Android? No. macOS with WhatsApp for Mac only.

• Will a WhatsApp update break it? Possibly; uv run wa status names what changed.

• Can the assistant grant itself more chats? Only with whatsapp_allow, which your client should ask you to approve each time.

• Can it find a chat the inbox no longer shows? Yes: whatsapp_chats with all (and grep) lists every chat.

License

MIT. Contributions: CONTRIBUTING.md.

Independent project, not affiliated with or endorsed by WhatsApp or Meta. Trademarks belong to their owners. Use it with your own account and respect the privacy of the people who write to you.