whatsapp-mcp

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