# 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:

```bash
cd whatsapp-bridge
npm install
```

### Step 2 — Install Python dependencies

```bash
pip install -r requirements.txt
```

---

## Every-time usage

### Step 1 — Start the WhatsApp bridge

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

```bash
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`

```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`.