whatsapp-mcp

Connect your WhatsApp to Claude Code. Read messages, transcribe audio, analyze images — all from your terminal, with full codebase context.

The real unlock isn't just reading messages. It's that Claude Code already knows your project — the architecture, the decisions, the debt. Now it also knows what your client just said on WhatsApp. Ask it to diagnose the bug they described, draft a reply that references actual code, or triage who needs attention most urgently.

# From inside your project directory:
"Read the last messages from Lucas and tell me if the issue he described
 is related to the auth refactor we did last week"

"Transcribe the audio João sent and create a GitHub issue with the requirements"

"Look at the screenshot Camila sent — what error is she seeing and where is it thrown?"

"Who's been waiting for a reply the longest?"

---

What it does

📨 Read

• All chats with unread messages at a glance
• Full message history with infinite backwards pagination
• Full-text search across your entire conversation history (SQLite FTS5)
• Contact and group info — participants, metadata, phone numbers

🎵 Audio → Text (local, offline)

Audio messages are automatically transcribed when you call get_media. Uses mlx-whisper with the large-v3-turbo model on Apple Silicon. No API key, no data leaving your machine, ~2–5s per message.

"Transcribe the voice note Rodrigo sent this morning"
→ [full transcript returned inline, ready for Claude to act on]

🖼️ Images → Claude sees them

Images aren't returned as file paths — they're sent as native MCP visual content blocks, so Claude receives and analyzes them directly.

"What does the screenshot Valentina sent show?"
→ Claude sees the image and describes the UI bug, error message, or whatever is in it

✍️ Write

• Send text messages with a human-like delay (avoids the "instant robot" feel)
• Reply quoting a specific message
• Send images with caption
• React with any emoji (or remove a reaction)
• Set presence: typing, recording, paused
• Mark chats as read

🧠 Intelligence tools

• find_pending_replies — which clients are waiting for you, sorted by recency
• get_chat_stats — message volume, media breakdown, active hours, date range
• export_chat — full conversation to Markdown or JSON
• sync_recent — force reconnect to recover messages missed during a gap

---

Real-world use cases

Client support with codebase context

"Read the last 10 messages from [client] and check if what they're
 describing matches the bug we logged in the database module"

Requirements from voice

"Transcribe the 3 audios Pedro sent today and write a PRD from them"

Visual debugging

"Daiana sent a screenshot — look at it and tell me what's broken and
 which component would throw that error"

Inbox triage

"I have 8 unread chats. Summarize each one in one sentence and tell
 me which needs a reply today"

Draft replies in your voice

"Reply to Camila — tell her the deploy is done and the image upload
 issue she reported is fixed. Keep it casual."

Turn WhatsApp into a task source

"Read everything Lucas sent this week and create Notion tasks for
 each thing he asked for"

---

Setup

Requirements

• macOS with Apple Silicon (M1/M2/M3/M4)
• Node.js 18+
• Python 3.11+
• Claude Code

1. Clone and install

git clone https://github.com/emawritz/whatsapp-mcp
cd whatsapp-mcp
npm install

2. Set up Whisper (local audio transcription)

./setup.sh

This creates a .venv, installs mlx-whisper, and pre-downloads the model (~1.5 GB, one-time). Sets WHISPER_PYTHON in .env automatically.

3. First run — scan QR code

npm run build
npm start

Scan the QR code with WhatsApp on your phone → Settings → Linked Devices → Link a Device.

Session is saved in auth_info_baileys/ — you only scan once.

4. Configure Claude Code

Add to ~/.claude.json:

{
  "mcpServers": {
    "whatsapp": {
      "type": "http",
      "url": "http://127.0.0.1:3001/mcp"
    }
  }
}

5. Run persistently with pm2 (recommended)

Running via pm2 means one WhatsApp connection shared across all Claude Code sessions — no conflicts, auto-restarts on crash, starts on boot.

npm install -g pm2
npm run build
pm2 start ecosystem.config.js
pm2 save
pm2 startup   # run the printed command with sudo

Why pm2? WhatsApp only allows one active session per linked device. Without pm2, each Claude Code terminal spawns its own process and they conflict (error 440). pm2 keeps one process alive for everyone.

---

Architecture

Claude Code  ←── MCP/HTTP ───►  whatsapp-mcp  ◄─── Baileys ───►  WhatsApp
                                      │
                                 SQLite (local)
                              mlx-whisper (local)

• Transport: StreamableHTTPServerTransport on localhost:3001 — stateless, one shared process
• Persistence: SQLite stores full message history, chat metadata, and encrypted proto for media downloads
• Audio: Python subprocess runs mlx-whisper with output silenced; transcript returned inline with the message
• Images: Returned as MCP image content blocks — Claude receives them visually, not as a path

---

Tools reference

Tool	What it does
get_unread_messages	All chats with unread messages
list_chats	N most recently active chats
get_chat_messages	Last N messages from a specific chat
search_messages	Full-text search across all history
get_contact_info	Contact or group metadata
load_more_history	Paginate further back in a chat's history
send_message	Send a text message (with human-like delay)
reply_to_message	Reply quoting a specific message
send_image	Send an image file with optional caption
react_to_message	Add or remove an emoji reaction
mark_as_read	Mark a chat as read
set_typing	Set typing / recording / paused presence
get_media	Download media; auto-transcribes audio, returns images visually
find_pending_replies	Chats waiting for your reply, newest first
get_chat_stats	Message volume, media types, active hours, date range
export_chat	Export full conversation to Markdown or JSON
sync_recent	Force reconnect to recover messages missed during a gap
backfill_media_proto	Recover downloadable media from historical connection gaps
edit_message	Edit the text of a previously sent message
delete_message	Delete (revoke for everyone) a previously sent message
get_message_context	Get N messages before and after a specific message for context

---

Stack

• Baileys — unofficial WhatsApp Web client
• MCP SDK — Model Context Protocol
• mlx-whisper — Apple Silicon Whisper
• better-sqlite3 — SQLite persistence
• pm2 — process management

---

Disclaimer

This project uses Baileys, an unofficial WhatsApp Web client. Using unofficial clients may violate WhatsApp's Terms of Service and could result in your account being banned. Use at your own risk. This project is not affiliated with or endorsed by WhatsApp or Meta.

---

License

MIT