wacrawl-mcp

Plug your WhatsApp into any AI assistant — locally, on your Mac. It's an MCP server, so it isn't tied to one app: any assistant that supports local MCP servers can search every chat, read threads, look at the photos and documents people sent you, understand voice notes (transcribed locally), and write messages — as drafts you send yourself or, if you turn it on, sent directly, with a check that they went out. The installer sets it up for Claude Desktop, and the examples below use Claude.

Everything runs on your computer. Your chats aren't uploaded anywhere (see Privacy).

Unofficial project. Not affiliated with WhatsApp, Meta or Anthropic.

What you can ask

• "What did Sam say about the proposal last week?"

• "Search all my chats for where we talked about the March invoice."

• "What are my last 5 chats? Did Ana reply?"

• "Show me the PDF Laura sent yesterday" or "read the Word doc they just sent me" — it actually reads them, even if they arrived a minute ago.

• "Save the photo of the contract from the group to my Downloads."

• "What did Martín say in yesterday's voice note?" — with local transcription.

• "Draft a follow-up to Pedro about what we discussed" — WhatsApp opens with the message typed; you send it.

• "Write personalized messages for these 6 people" — they open one at a time, as you send each one.

• "Send Ana: running 10 minutes late" — with direct sending turned on, Claude sends it and checks that it went out.

Related MCP server: WhatMCP

Ask for the outcome, not the search

The point isn't a WhatsApp search box inside a chat. It's that you stop explaining: the assistant reads the conversations itself, so you skip the who, the where and the copy-pasting, and just ask for the result. It gets better combined with whatever else the assistant is connected to — calendar, email, meeting notes, your files:

• "Do what Sofía asked me for this morning, and send her the reply when I say so." — it finds the request, does the work with its other tools, and has the answer ready to go.

• "Do what the lawyer asked for in today's meeting." — the meeting notes say what; the WhatsApp thread with the lawyer brings the background nobody wrote down.

• "Who came to my last three birthdays? Make a list of the friends I should invite, 30 at most, and invite them." — it works out the list from those chats and queues a personal invitation for each one (the safeguards won't let it send everyone the same text, and they cap how many go out per hour).

• "What did people ask me this week that I still haven't answered?"

• "I have a call with Marcos in ten minutes. What's pending between us?"

• "Put the visit the landlord confirmed on my calendar, with the address he sent."

None of these says which chat to open or which dates to look at: that's the part you no longer do.

How it works

flowchart LR
  WA["WhatsApp Desktop<br/>(Mac app)"] -->|sync every 6 h| W[wacrawl]
  W --> A[("local archive<br/>~/.wacrawl")]
  A --> S[wacrawl-mcp]
  WA -->|live reads| S
  S -->|drafts and sends| WA
  S <-->|MCP over stdio| C[Claude Desktop]

• wacrawl reads WhatsApp Desktop's local database and keeps a searchable SQLite archive, refreshed by a background sync every 6 hours.

• This server gives Claude tools over that archive, plus live reads of WhatsApp Desktop for whatever arrived in the last few hours.

• Writing goes through the official app: a whatsapp:// link opens the chat with the text typed in. Direct sending (opt-in) presses Enter for you and checks WhatsApp's database to confirm the message went out.

One file (server.js), no npm dependencies, no network.

Tools

Requirements

Voice note transcription also needs an Apple Silicon Mac (M1 or later).

Claude doesn't need skills, plugins or any extra setup: the server tells Claude how to use each tool and how to read the results.

Install

1. Clone the repo and run the installer (in Terminal):

git clone https://github.com/renzactus/wacrawl-mcp.git ~/wacrawl-mcp
cd ~/wacrawl-mcp
./install.sh

It checks the requirements, installs wacrawl (verifying its checksum), builds your local archive, sets up an automatic sync every 6 hours, and tells you what's left. The first import takes a few minutes.

If macOS asks whether Terminal can access data from other apps, allow it: that's how it reads WhatsApp.

2. Grant Full Disk Access (macOS doesn't let a script do it):

System Settings → Privacy & Security → Full Disk Access → + → ⌘⇧G → paste the path the installer showed you (it ends in /runtime/bin/node) → Open → turn it on.

That permission is only for a copy of node used exclusively by this server — not for your system's node — so no other program inherits it. Almost everything works without it; you just can't see what arrived seconds ago or use the draft queue.

3. Register it with Claude, with Claude quit:

Quit Claude Desktop with ⌘Q (closing the window isn't enough) and run:

~/wacrawl-mcp/register.sh

Open Claude Desktop. Done.

Why it has to be quit: Claude Desktop reads its configuration when it starts and rewrites it when it quits. If you edit it while the app is open, quitting erases what you added. The script refuses to run if it sees Claude open. If the installer found Claude closed, it already did this step.

The server speaks plain MCP over stdio, so other MCP clients can run it too; the scripts set up Claude Desktop.

Check that it works

Ask Claude: "what are my last 3 WhatsApp chats?"

If something's off, run the diagnostic — it shows how each message type renders, whether times are right, how far behind the archive is, and whether the automatic sync is working:

~/wacrawl-mcp/check.sh

(It uses python3; if macOS offers to install the developer tools, accept.)

Privacy

What stays on your Mac: all of your WhatsApp. The archive (~/.wacrawl/), the images and documents, and the server itself. None of it is uploaded anywhere.

What leaves your Mac: only what Claude reads to answer you. If you ask about a chat, the messages it looks at go into that Claude conversation, just as if you had pasted them, and they stay in your Claude history like any other chat.

Shared Claude accounts: access to your WhatsApp belongs to your Mac, not to the account. Someone signing in to the same account from another computer can not query your WhatsApp. But they can see your Claude conversations, including any WhatsApp messages Claude read in them. If several people share an account, each should assume the others see what they looked up. One account per person is the way to go (a Team plan, for example).

Nothing is sent unless you turn it on. By default Claude can only leave a message typed in WhatsApp, and you're the one who presses Enter. Direct sending is off.

Sending messages

Three levels, from the most to the least hands-on:

Drafts

• One: "draft a message to Ana saying…"

• Several: "write messages for these people and queue them up". The first one opens; when it detects you sent it, it opens the next one (~3 s). If you take your time with one, it waits. If you don't send one within 10 minutes, the queue pauses. You can say skip, resume or cancel.

Direct sending (optional, off by default)

Claude can send the message, not just leave it typed: it opens the chat in WhatsApp Desktop, presses Enter, and checks WhatsApp's database to confirm it went out. It goes through the official app — no unofficial client involved.

It's off on purpose: sending messages in your name is your call. To turn it on:

~/wacrawl-mcp/enable-sending.sh

The script turns it on and opens the Accessibility settings with the path already copied: click +, ⌘⇧G, paste, Open, and turn it on (that's what lets it press Enter). Then quit (⌘Q) and reopen Claude Desktop. The first time, macOS may ask whether it can control "System Events": allow it.

To turn it off: ~/wacrawl-mcp/enable-sending.sh --off (it takes effect without restarting).

Recommended: let Claude Desktop ask for your permission every time it uses send_message (don't pick "always allow"). It's the last safeguard, and the model can't skip it.

Safeguards

They live in code, not in the prompt (a runaway model ignores instructions, not an if), and their counters are saved on disk so restarting doesn't reset them:

• at most 3 drafts per minute and 15 per hour, and at most 10 sends per hour

• never the same text to several people (the broadcast pattern WhatsApp punishes)

• one-to-one chats only: WhatsApp doesn't open groups this way

• a warning when it's a number you've never talked to

• a send only presses Enter if WhatsApp is the frontmost app (otherwise the Enter would land in another app), and if it can't confirm the message went out it doesn't retry, so nothing goes out twice

• emergency stop: touch ~/.wacrawl/STOP stops every draft and send; delete the file to turn them back on

You can adjust them in ~/.wacrawl/limits.json, for example {"perHour": 40, "antiBroadcast": false}. Keys: perMinute, perHour, sendsPerHour, maxLength, antiBroadcast, queueMax, queueWaitMin, allowSending.

Careful with cold messages. Going through the official app avoids the risks of an unofficial client, but WhatsApp's terms forbid bulk and automated messaging, and WhatsApp can restrict a number that many strangers block or report. Keep the volume low and the messages genuinely personal. Your account, your responsibility.

Voice notes (optional)

Transcribes your voice notes on your Mac, without sending them anywhere, with Whisper (the same kind of model paid services use). Claude then reads them as text and finds them in searches: "which voice note mentioned the price?" works.

~/wacrawl-mcp/setup-whisper.sh

• Needs a Mac with an Apple chip (M1 or later). It downloads the model once (~1.6 GB).

• It asks for the language of your voice notes, or detects it per note. You can change it in ~/.wacrawl/whisper.env (e.g. WHISPER_LANGUAGE=en).

• It transcribes every voice note on disk in the background (≈2 s each, without slowing the Mac down: it runs on the GPU), and after that the new ones on every automatic sync.

• If you ask about one that hasn't been processed yet, Claude transcribes it on the spot.

• It runs at ~13-17× real time: a 1-minute voice note takes about 4 seconds.

Quality: very good with Rioplatense Spanish, where it was measured. The weak spot is uncommon proper names — especially your company's, if it isn't a dictionary word. Measured without help, a company name came out right only 1 time in 4. That matters more for searching than for understanding: Claude can tell that "viatic" means "Viatik" when reading, but a search for "Viatik" never finds that voice note.

That's what the vocabulary is for (~/.wacrawl/vocabulary.txt): a priority-ordered list of the names you use. It doesn't train anything — it's a hint Whisper gets with every voice note. The installer builds a suggested one from what you write on WhatsApp; review it and put your company, team and clients at the top. In groups, the names of the people who talk most there are added automatically.

Measured with a vocabulary, on 20 voice notes where the company name came out wrong: from 0 to 11 right, and on another 8, a nickname from 1 to 7; without inventing names in voice notes where they weren't said, and no slower.

If you edit the vocabulary, re-transcribe the old ones (in the background; it resumes if interrupted):

~/wacrawl-mcp/redo-transcriptions.sh

It only transcribes voice notes that are on your Mac (the ones WhatsApp Desktop downloaded since you linked it).

Import years of history from your iPhone (optional)

WhatsApp Desktop only receives about a year when it's linked, and there's no way to ask it for more. The iPhone has everything. With a wired iPhone backup, the rest is imported once into a separate archive (~/.wacrawl/historico); Claude searches both as if they were one.

Before you start — what can't be done, or takes effort:

• iPhone only. On Android the backup is encrypted differently and this script can't read it.

• WhatsApp's iCloud backup doesn't work (encrypted, no access). It has to be the Finder backup.

• Finder copies the whole iPhone, not just WhatsApp. It's temporary, but it has to fit on the disk: check Settings → General → iPhone Storage to see how much you use. If it doesn't fit, free up space first.

• Old attachments come back only if the iPhone still has them. By default videos and stickers are left out (they're usually half the space, and Claude can't look at them).

• It's a snapshot: whatever arrives after the backup comes in through the usual sync.

Steps:

1. In Finder, with the iPhone connected: Back up all of the data on your iPhone to this Mac, without Encrypt local backup (if it's ticked, untick it for this backup; Finder asks for the password). Back Up Now.

2. macOS won't let a script read the backup where Finder keeps it. Open it and move it:

   mkdir -p ~/iphone-backup && open ~/iphone-backup && open ~/Library/Application\ Support/MobileSync/Backup

   Drag the backup folder (a long name like 00008140-…, the newest one) to iphone-backup. It's instant and takes no extra space.

3. Import it (about 15 minutes; add --with-videos if you want everything):

   ~/wacrawl-mcp/import-iphone.sh ~/iphone-backup/<folder>

4. Delete the backup: select the folder in Finder and press ⌥⌘⌫. The WhatsApp part has already been taken out.

Old voice notes aren't transcribed on their own: Claude transcribes them on demand. To do them all, leave the Mac plugged in with the lid open for one or several nights (an M4 transcribes about 10× faster than the audio lasts: 300 hours of audio take more than a day). It goes from newest to oldest, can be stopped, and resumes where it left off:

~/wacrawl-mcp/transcribe-history.sh                  # or with a date: … 1 2026-01-01 (only older ones)
~/wacrawl-mcp/transcribe-history.sh status           # progress, per year
~/wacrawl-mcp/transcribe-history.sh stop

What it doesn't do (worth knowing)

• It doesn't have your whole history unless you import the iPhone's. It has what WhatsApp Desktop received from the phone when it was linked (usually about a year) plus everything since. If something old doesn't show up, it isn't on your Mac.

• The archive can be up to 6 hours behind. Updating it takes minutes, so it happens in the background. For anything very recent, Claude reads WhatsApp live (that needs the permission from step 2).

• In big groups, many messages have no sender name: WhatsApp doesn't store the names of people who aren't in your contacts. One-to-one chats don't have this problem.

• Files (photos, PDFs, documents) only exist since you linked WhatsApp Desktop, plus the ones an iPhone history brings back. Word files are read in full; Excel files have to be exported.

• Voice notes are only transcribed if you install local transcription; otherwise Claude knows they exist but not what they say.

• Drafting or sending needs the phone number. It works with your saved contacts; for people you haven't saved, WhatsApp hides the number and you have to give it.

• If someone is saved under a nickname, look them up the way you saved them.

Troubleshooting

Automatic sync log: ~/.wacrawl/wrapper.log.

Update

cd ~/wacrawl-mcp && git pull

Quit and reopen Claude Desktop (⌘Q). There's no need to register again or to grant the permissions again.

Uninstall

launchctl bootout gui/$(id -u)/io.github.renzactus.wacrawl-mcp.sync
rm ~/Library/LaunchAgents/io.github.renzactus.wacrawl-mcp.sync.plist

With Claude quit, remove the "wacrawl" block from ~/Library/Application Support/Claude/claude_desktop_config.json, and remove the node entry from Full Disk Access (and from Accessibility, if you turned on sending). Your WhatsApp archive stays in ~/.wacrawl/: delete it only if you're sure, because it may have messages your WhatsApp no longer has.

Windows or Linux

This depends on reading the files of WhatsApp Desktop for Mac. For Windows and Linux, the makers of wacrawl also have wacli: it links as a device with a QR code, keeps everything in a local SQLite database and has Windows binaries. A server like this one could be built on top of it.

Credits

• wacrawl by OpenClaw (MIT) builds and syncs the local archive. The installer downloads it from its official releases and checks its checksum; it isn't bundled here.

• Whisper by OpenAI (MIT), run through Apple's mlx-whisper (MIT), does the transcription.

• uv by Astral (MIT or Apache-2.0) fetches Python and the transcription libraries.

How it's built, why each decision was made, and the things that are expensive to rediscover: TECHNICAL-NOTES.md.

License

MIT © 2026 Renzo Costanzo