whatsapp-hermes

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.

Features

• 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

MCP Tools

Tool	Purpose	Params
whatsapp_status	Connection + pairing state	—
whatsapp_send	Send a text message	to (number or JID), message
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).

Prerequisites

• Node.js 18+
• A phone with WhatsApp (to scan the pairing QR)

Install

git clone https://github.com/RicSchonfelder/whatsapp-hermes.git
cd whatsapp-hermes
npm install
cp .env.example .env      # then edit .env

Set 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=*

First-time pairing

Run once to pair, without needing an MCP host:

npm run pair

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

Register with Hermes

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.

Protocol note (important)

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.

Security

• wa_auth/ holds full session credentials — it is git-ignored. Never commit or share it. Treat it like a password.
• Always set WHATSAPP_ALLOWED_NUMBERS before exposing the agent.
• Prefer a dedicated phone number for the bot.

Manutencao

Secrets que nunca devem ser commitados

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

Limpeza de artefatos temporarios

O projeto gera arquivos operacionais que podem ser removidos sem risco:

bash scripts/cleanup.sh

O script remove apenas *.log e qr_pair.png na raiz do projeto. Ele nunca toca em wa_auth/ ou .env.

Arquivos de log

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.

License

MIT © RicSchonfelder