# WhatsApp MCP Server Setup

**Date:** 2026-02-12 22:50
**Context:** Built full-featured WhatsApp MCP server with consumer account support via whatsapp-web.js

## Architecture

```
Claude Code (Mac) → MCP Server (stdio) → HTTP API → Docker Container (NUC) → whatsapp-web.js → WhatsApp
```

## Container Details

| Property | Value |
|----------|-------|
| **Container** | `whatsapp-mcp` |
| **Port** | `3100` |
| **QR Page** | `http://192.168.1.3:3100/qr` |
| **API Token** | `2d86b48f0fefc044c5bad974c4f9df2c8cc6c905dc3a10dfff203e6717b02d7c` |
| **Volumes** | `whatsapp-auth` (session), `whatsapp-media` (downloads) |
| **Image** | `whatsapp-mcp-whatsapp` (multi-stage, ~700MB) |
| **Source on NUC** | `~/whatsapp-mcp/` |
| **MCP Source** | `~/mcp-servers/whatsapp-mcp/` |

## MCP Tools (27 total)

### Status & Connection
- `whatsapp_get_status` - Connection status, phone, name
- `whatsapp_get_qr_code` - QR code for pairing
- `whatsapp_logout` - Disconnect

### Sending
- `whatsapp_send_message` - Text message
- `whatsapp_send_media` - Image/video/doc/audio
- `whatsapp_send_location` - Location pin
- `whatsapp_reply_to_message` - Quoted reply
- `whatsapp_react_to_message` - Emoji reaction
- `whatsapp_forward_message` - Forward to another chat

### Reading
- `whatsapp_get_messages` - Chat history
- `whatsapp_get_new_messages` - Poll new incoming
- `whatsapp_search_messages` - Text search

### Contacts
- `whatsapp_list_contacts` - All contacts
- `whatsapp_get_contact` - Contact details
- `whatsapp_search_contacts` - Search by name/phone
- `whatsapp_check_phone_numbers` - Check registration

### Groups
- `whatsapp_list_groups` - All groups
- `whatsapp_get_group` - Group details
- `whatsapp_create_group` - Create new group
- `whatsapp_update_group` - Update name/description
- `whatsapp_manage_participants` - Add/remove members

### Chats
- `whatsapp_list_chats` - All chats with metadata
- `whatsapp_mark_chat_read` - Mark as read
- `whatsapp_archive_chat` - Archive/unarchive

### Media & Presence
- `whatsapp_download_media` - Download media from message
- `whatsapp_send_typing` - Show typing indicator

## Pairing

1. Open `http://192.168.1.3:3100/qr` in browser
2. Open WhatsApp → Linked Devices → Link a Device
3. Scan the QR code
4. Session persists in `whatsapp-auth` volume (no re-scan after restart)

## Management

```bash
# Restart
ssh nuc "cd ~/whatsapp-mcp && docker compose restart"

# Logs
ssh nuc "docker logs whatsapp-mcp -f"

# Rebuild
scp -r ~/mcp-servers/whatsapp-mcp/service/src nuc:~/whatsapp-mcp/service/
ssh nuc "cd ~/whatsapp-mcp && docker compose build && docker compose up -d"
```

## Related
- MCP registered as `whatsapp` in `~/.claude.json` (user scope)
- Pattern matches stalwart-mail MCP (local stdio → remote HTTP)