WhatsApp MCP

MCP server for WhatsApp that connects to your personal WhatsApp account via the WhatsApp Web multi-device API (using the whatsmeow library). Single Go binary — no Python or separate bridge process needed. All messages are stored locally in SQLite and only sent to the LLM when accessed through tools.

Installation

Option A — Install script (macOS / Linux, no Go required)

curl -fsSL https://raw.githubusercontent.com/ihiteshgupta/whatsapp-mcp/main/install.sh | sh

Installs the whatsapp-mcp binary to /usr/local/bin.

Option B — Homebrew (macOS / Linux)

brew install ihiteshgupta/tap/whatsapp-mcp

Requires the Homebrew tap to be set up. See ihiteshgupta/homebrew-tap.

Option C — go install (Go users)

go install github.com/ihiteshgupta/whatsapp-mcp/whatsapp-bridge-v2/cmd/whatsapp-mcp@latest

Option D — Build from source

git clone https://github.com/ihiteshgupta/whatsapp-mcp.git
cd whatsapp-mcp/whatsapp-bridge-v2
go build -o whatsapp-mcp ./cmd/whatsapp-mcp

Windows: CGO is required for SQLite. Install MSYS2, add ucrt64\bin to PATH, then run go env -w CGO_ENABLED=1 before building.

Configure your MCP client

Claude Desktop / Claude Code

Add to your Claude config:

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Code: ~/.claude.json

{
  "mcpServers": {
    "whatsapp": {
      "command": "/usr/local/bin/whatsapp-mcp",
      "args": []
    }
  }
}

Replace /usr/local/bin/whatsapp-mcp with the actual path if you built from source (e.g. /path/to/whatsapp-mcp/whatsapp-bridge-v2/whatsapp-mcp).

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "whatsapp": {
      "command": "/usr/local/bin/whatsapp-mcp",
      "args": []
    }
  }
}

3. Authenticate

1. Start your MCP client (Claude Desktop, Claude Code, or Cursor)
2. A QR code will appear in the terminal and be saved to ~/.whatsapp-mcp/qrcode.png
3. Scan with WhatsApp on your phone (Settings → Linked Devices → Link a Device)
4. Wait for history sync to complete
5. Session persists in ~/.whatsapp-mcp/whatsapp.db — re-authentication needed every ~20 days

Data Storage

All data is stored locally in ~/.whatsapp-mcp/ (no config file needed):

• ~/.whatsapp-mcp/whatsapp.db — WhatsApp session (whatsmeow)
• ~/.whatsapp-mcp/messages.db — Messages, chats, contacts, groups
• ~/.whatsapp-mcp/qrcode.png — QR code image (created on first launch)

MCP Tools (55 total)

Messaging (8)

Chats (11)

Contacts (6)

Groups (13)

Media (7)

Presence (5)

Status (4)

Bridge (2)

Troubleshooting

• QR Code not appearing: Check stderr output, or open ~/.whatsapp-mcp/qrcode.png
• Session expired: Delete ~/.whatsapp-mcp/whatsapp.db and restart to re-authenticate
• Out of sync: Delete both ~/.whatsapp-mcp/*.db files and restart
• Windows CGO error (Binary was compiled with 'CGO_ENABLED=0'): Install MSYS2, add ucrt64\bin to PATH, run go env -w CGO_ENABLED=1
• Device limit reached: Remove a device in WhatsApp → Settings → Linked Devices

Security Note

As with all MCP servers, be aware of prompt injection risks. This server can read your WhatsApp messages and send messages on your behalf — only connect trusted AI clients.

Development

cd whatsapp-bridge-v2
go test ./...
go build ./...

License

MIT