Claude Whatsapp Mcp

claude-whatsapp-mcp

WhatsApp MCP server for Claude Code. Read messages, send replies, search contacts — all from your terminal.

Built with whatsapp-web.js and the Model Context Protocol.

What it does

Give Claude Code direct access to your WhatsApp:

• Read chats — "check my unreads", "what did Ali say?"
• Send messages — "send John the proposal PDF"
• Search contacts — "find Sarah's number"
• Connection management — QR code auth, session persistence

Setup

1. Clone and install

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

2. Add to Claude Code

Add this to your Claude Code MCP settings (~/.claude.json or project .mcp.json):

{
  "mcpServers": {
    "whatsapp": {
      "command": "node",
      "args": ["/path/to/claude-whatsapp-mcp/src/index.js"]
    }
  }
}

3. Connect WhatsApp

In Claude Code, just say:

connect to whatsapp

Claude will initialize the server and show you a QR code. Scan it with your phone (WhatsApp > Settings > Linked Devices > Link a Device).

Your session persists in .wwebjs_auth/ — you only need to scan once.

Tools

| Tool | Description | |------|-------------| | whatsapp_connect | Connect to WhatsApp or check status. Shows QR if needed. | | whatsapp_send_message | Send text + optional file attachment | | whatsapp_list_chats | List recent chats with unread counts | | whatsapp_read_chat | Read messages from a specific chat | | whatsapp_search_contacts | Search contacts by name or number | | whatsapp_status | Connection status + unread summary |

Usage examples

# Check unreads
"do I have any unread WhatsApp messages?"

# Read a specific chat
"what's the latest in my family group?"

# Send a message
"send Ali a message saying the meeting is at 3pm"

# Send a file
"send the invoice PDF to +60123456789"

# Search contacts
"find contacts named Sarah"

Requirements

• Node.js 18+
• Claude Code with MCP support
• A WhatsApp account

How it works

The server runs whatsapp-web.js locally on your machine — the same tech as WhatsApp Web. Your messages stay on your device. Nothing is sent to any external server.

On first run, it generates a QR code for linking. After that, the session is cached and reconnects automatically.

License

MIT

---

Built by Adletic Agency

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ferazfhansurie
• Source: ferazfhansurie/claude-whatsapp-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.