WhatsApp MCP Server

Connect your personal WhatsApp to Claude — send messages, read chats, and manage contacts.

---

How it works

Claude ←→ Python MCP server (server.py)
                    ↕  HTTP localhost:3000
          Node.js WhatsApp bridge (whatsapp-bridge/)
                    ↕  WhatsApp Web protocol
              Your personal WhatsApp

---

Prerequisites

Tool	Download
Node.js ≥ 18	https://nodejs.org
Python ≥ 3.10	https://python.org
Google Chrome	(already installed on most machines)

---

One-time setup

Step 1 — Install bridge dependencies

Open a terminal in this folder and run:

cd whatsapp-bridge
npm install

Step 2 — Install Python dependencies

pip install -r requirements.txt

---

Every-time usage

Step 1 — Start the WhatsApp bridge

Double-click start_bridge.bat (or run in a terminal):

cd whatsapp-bridge
node index.js

A QR code will appear. On your phone:

• Open WhatsApp → Settings → Linked Devices → Link a Device
• Scan the QR code

The terminal will show 🟢 WhatsApp bridge ready when connected.

Keep this terminal open while using Claude. If you close it, Claude loses access to WhatsApp.

Step 2 — Connect Claude to the MCP server

Add the following to your Claude Desktop config file:

Config file location:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "whatsapp": {
      "command": "python",
      "args": ["C:\\Users\\pc\\Claude\\Projects\\Whatsup MCP\\server.py"]
    }
  }
}

Replace the path if you moved this folder.

Step 3 — Restart Claude Desktop

After saving the config, fully quit and reopen Claude Desktop. You should see a 🔌 WhatsApp connection in the tools panel.

---

Available tools

Tool	What it does
whatsapp_get_status	Check connection state
whatsapp_list_chats	List recent conversations
whatsapp_get_messages	Read messages from a chat
whatsapp_list_contacts	List your contacts
whatsapp_send_message	Send a text message

---

Example prompts for Claude

• "Show my recent WhatsApp chats"
• "Read the last 10 messages from Priya"
• "Send 'On my way!' to Rahul on WhatsApp"
• "List all my WhatsApp group chats"

---

Troubleshooting

"Cannot reach the WhatsApp bridge" → Make sure start_bridge.bat is running and shows 🟢 WhatsApp bridge ready.

QR code expired → Restart the bridge — a new QR will appear. You only need to scan once per session (auth is saved in whatsapp-bridge/.wwebjs_auth).

"puppeteer" / Chrome error on startup → Make sure Google Chrome is installed. If you have a custom Chrome path, add this to whatsapp-bridge/index.js inside the puppeteer block: executablePath: 'C:\\Path\\To\\chrome.exe'

Messages not sending → Use whatsapp_list_contacts to get the correct chat ID, then pass that ID to whatsapp_send_message.