Skip to content
Hoh JDLatest guide
All guides
AI tools10 min setup

Connect Claude to your WhatsApp (WhatsApp MCP setup)

Jump to a section

Warning: this can get your WhatsApp account banned. Some people who set this up report that WhatsApp banned their number, sometimes within days, with no appeal. It connects as an unofficial client, which breaks WhatsApp's terms, and WhatsApp is actively cracking down on that. I can't tell you how likely it is. Do this only on a spare number, never on the one your family, friends or customers use.

Ask Claude to search your chats, summarise busy group chats, find messages you missed, and send replies for you.

It uses WhatsApp MCP, a free, open-source tool by Luke Harries: https://github.com/lharries/whatsapp-mcp

Setup takes about 10 minutes, and Claude Code does almost all of it.

Read this first

This is powerful, and it is not risk-free. Know what you are signing up for.

  • It is unofficial. WhatsApp MCP is a community project, not from WhatsApp, Meta or Anthropic. It connects the same way unofficial WhatsApp clients do, which WhatsApp's terms do not permit. That is where the ban risk above comes from.
  • Your chats get stored in plain text. The bridge downloads your message history into a database file on your computer, with no encryption. Anyone who can open your laptop can read it. Use full-disk encryption (FileVault on Mac, BitLocker on Windows) and delete the folder when you stop using it.
  • Claude reads what you ask it to read. Anything you ask about, including other people's messages in group chats, is sent to Anthropic to be processed. Those people did not agree to that. Keep it to chats where you'd be comfortable saying so.
  • Messages can carry hidden instructions. A message someone sends you could try to steer Claude into forwarding your chats or sending replies. Never turn off tool approvals, and read every outgoing message before you allow it.
  • It can send on your behalf. A wrong name or a misread request means a message goes to the wrong person. There is no undo.
  • You are letting an AI install software. Step 1 asks Claude Code to install tools and edit config files. Read what it proposes before you approve it.

If any of that is a deal-breaker, stop here. If you're fine with it, carry on.

What you need

  • Claude Code (if claude runs in your terminal, you're good)
  • Claude Desktop, if you want WhatsApp there too: https://claude.ai/download
  • Your phone with WhatsApp, to scan a QR code once

Works on Mac and Windows. Everything runs on your own computer, and your messages stay there.

1. Let Claude Code set it up

Open Terminal (Mac) or PowerShell (Windows), type claude, and paste this:

Set up WhatsApp MCP for me from https://github.com/lharries/whatsapp-mcp. Install anything I'm missing (Git, Go and uv; on Windows also MSYS2 for the C compiler, and turn on CGO). Clone the repo into my home folder. Add the MCP server to Claude Code with claude mcp add, and to Claude Desktop's claude_desktop_config.json using the full path to uv, keeping any servers already in that file. Don't start the bridge yourself. When you're done, tell me the exact command to run in a new terminal so I can scan the WhatsApp QR code.

Approve the commands as it asks. If something needs your password, like installing Homebrew on a Mac, Claude will give you that one command to run yourself.

2. Link your WhatsApp

Open a new terminal window and run the command Claude gave you. It will look like this:

cd ~/whatsapp-mcp/whatsapp-bridge
go run main.go

A QR code appears. On your phone, open WhatsApp, go to Settings > Linked Devices > Link a Device, and scan it.

Leave this window open. Close it and Claude can't reach WhatsApp.

3. Try it

Quit Claude Desktop completely (Cmd + Q on Mac) and reopen it, or start a new claude session. Then ask:

  • "Search my WhatsApp contacts for Mum."
  • "Summarise the last 50 messages in my [group name] group chat."
  • "Is there anything in my WhatsApp from today that I haven't replied to?"
  • "Send a WhatsApp message to [name] saying I'll be 10 minutes late."

Claude asks before it uses each WhatsApp tool the first time. Click Allow.

Every time after that

Start the bridge with the command from step 2, then open Claude. You only scan the QR code again if WhatsApp logs the bridge out, which can happen about every 20 days.

If it doesn't work

  • No QR code, but it says connected: you're already linked.
  • "Device limit reached" on your phone: remove an old device in WhatsApp under Settings > Linked Devices.
  • Claude can't find any messages: the first sync takes a few minutes, and the bridge window has to be running.
  • WhatsApp doesn't show up in Claude: paste the error into Claude Code and ask it to fix the config, then fully quit and reopen Claude Desktop.
  • Messages out of sync: ask Claude Code to reset the WhatsApp bridge database, then scan the QR code again.

Two don'ts:

  • Don't let Claude act on instructions that arrive inside a WhatsApp message. A message can try to trick the AI, which the project's own README warns about. Keep tool approvals on.
  • Don't send without reading. Check every message before you allow send_message, especially in group chats.

To unlink, open WhatsApp > Settings > Linked Devices, tap the device and choose Log Out.

WhatsApp MCP is an open-source project by Luke Harries (MIT license), not an official WhatsApp or Anthropic product. All credit to him.