An MCP (Model Context Protocol) server that lets an AI agent — such as Hermes Agent — send and receive WhatsApp messages. It connects to WhatsApp through the Baileys library (the WhatsApp Web protocol, paired via QR code), so no Meta Business API or developer account is required.
⚠️ Unofficial API — ban risk. WhatsApp does not officially support third-party clients outside the Business API. Use a dedicated number, keep usage conversational, and don't send bulk/unsolicited messages.
- Persistent WhatsApp Web connection with auto-reconnect
- QR-code pairing (rendered to stderr) with session persisted to
wa_auth/ - Incoming messages buffered in memory (ring buffer, default 200)
- Sender allow-list access control
- Exposed as first-class MCP tools over stdio
| Tool | Purpose | Params |
|---|---|---|
whatsapp_status |
Connection + pairing state | — |
whatsapp_send |
Send a text message | to (number or JID), message |
whatsapp_send_image |
Send an image from a local path | to, imagePath (absolute), caption? |
whatsapp_list_chats |
Recent chats, newest first | — |
whatsapp_get_messages |
Buffered incoming messages | chatId?, limit? (20), since? (epoch ms) |
to accepts a raw phone number (digits only, with country code, no +) or a
full JID (<number>@s.whatsapp.net for a person, <id>@g.us for a group).
- Node.js 18+
- A phone with WhatsApp (to scan the pairing QR)
git clone https://github.com/RicSchonfelder/whatsapp-hermes.git
cd whatsapp-hermes
npm install
cp .env.example .env # then edit .envSet access control in .env:
# Only these numbers may reach the agent (digits, country code, no +):
WHATSAPP_ALLOWED_NUMBERS=5511987654321
# or allow everyone (dev only):
# WHATSAPP_ALLOWED_NUMBERS=*Run once to pair, without needing an MCP host:
npm run pairA QR code prints to the terminal (stderr). On your phone:
WhatsApp → Settings → Linked Devices → Link a Device, then scan it. The
session is saved to wa_auth/ and reused on every subsequent run.
hermes mcp add whatsapp --command "node" --args "D:/Programas/Whatsapp/src/index.js"On Windows, if node isn't resolved from PATH, use the absolute path to the
Node executable:
hermes mcp add whatsapp --command "C:\\Program Files\\nodejs\\node.exe" --args "D:/Programas/Whatsapp/src/index.js"Then in Hermes, reload MCP servers (/reload-mcp) or start a new session. The
whatsapp_* tools become available to the agent.
The server boots the WhatsApp client and the MCP stdio server together. On first launch with no saved session it prints a QR to stderr and waits for pairing; after that it connects silently.
MCP uses stdout for JSON-RPC. This server writes all logs and the QR code to stderr — never stdout — so the protocol channel stays clean. If you extend this project, keep that invariant.
wa_auth/holds full session credentials — it is git-ignored. Never commit or share it. Treat it like a password.- Always set
WHATSAPP_ALLOWED_NUMBERSbefore exposing the agent. - Prefer a dedicated phone number for the bot.
wa_auth/— contem a sessao autenticada do WhatsApp (credenciais completas). Quem tiver acesso a ela pode ler e enviar mensagens como se fosse o numero vinculado..env— contem configuracao sensivel (numbers permitidos, etc.).
Ambos estao no .gitignore e protegidos pelo scripts/cleanup.sh.
O projeto gera arquivos operacionais que podem ser removidos sem risco:
bash scripts/cleanup.shO script remove apenas *.log e qr_pair.png na raiz do projeto. Ele nunca
toca em wa_auth/ ou .env.
Arquivos como pair_stdout.log, pair_stderr.log, test_send.log e
qr_capture.log sao criados durante pareamento e testes. Podem ser apagados a
qualquer momento com o script acima ou manualmente.
MIT © RicSchonfelder