Enables sending and receiving WhatsApp messages using the Baileys library, supporting text, images, chat listing, and message retrieval.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@whatsapp-hermes send 'Good morning' to 5511987654321"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Related MCP server: WhatsApp MCP Server (TypeScript)
Tool | Purpose | Params |
| Connection + pairing state | — |
| Send a text message |
|
| Send an image from a local path |
|
| Recent chats, newest first | — |
| Buffered incoming messages |
|
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_NUMBERS before 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
Get buffered incoming messages, newest first. Optionally filter by chatId and/or a 'since' epoch-ms timestamp, and cap with 'limit'.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max messages to return (default 20). | |
| since | No | Only messages at/after this epoch-ms timestamp. | |
| chatId | No | Filter to a specific chat JID (from whatsapp_list_chats). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits, but it only mentions 'buffered' and 'newest first'. It does not explain whether messages are consumed (removed) after retrieval, which is critical for a buffered message tool. No information about rate limits, pagination, or empty-buffer behavior is provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that communicates purpose and core options without filler. Every word contributes value, and the structure is ideal for quick understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and no annotations, so the description should cover return value format and behavioral side effects. It mentions filtering and ordering but omits what the returned message objects look like and whether the buffer is drained. This leaves important gaps, though the core filtering logic is clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema coverage is 100%, so each parameter already has a description. The tool description merely rephrases the filter options ('chatId', 'since', 'limit') without adding extra semantics like value formats or interaction effects. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a clear verb and resource: 'Get buffered incoming messages' and specifies ordering ('newest first'). This distinguishes it from sibling tools like whatsapp_send or whatsapp_list_chats, which are about sending or listing chats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use it: retrieving buffered incoming messages. It does not explicitly exclude alternatives, but the context is unambiguous since the sibling tools have different purposes. The absence of exclusions is acceptable for a straightforward read tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List recent chats seen since the server started, newest first, with the last message preview.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the temporal scope ('since the server started'), sorting ('newest first'), and content ('last message preview'), which are meaningful behavioral traits. It does not mention pagination or empty-state behavior, but for a simple read-only list tool this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the verb and resource, with no wasted words. Every phrase adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no output schema), the description provides enough information to understand the outcome: a list of recent chats with previews. It does not detail the exact return format, but that is not critical for selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is 100%, so there is nothing for the description to add about parameters. The baseline for no parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('recent chats'), and adds scope ('since the server started'), ordering ('newest first'), and content ('last message preview'). This clearly distinguishes it from siblings like whatsapp_get_messages or whatsapp_send.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the usage context: when you need an overview of recent chats rather than specific messages. It does not explicitly name alternatives or exclusions, but the purpose and phrasing make the appropriate use case clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a WhatsApp text message. 'to' may be a raw phone number (digits, country code, no +) or a full JID (…@s.whatsapp.net for a person, …@g.us for a group).
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Phone number (digits only, with country code) or a full JID. | |
| message | Yes | The text to send. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It explains address formats but does not disclose side effects, authentication requirements, or failure behavior. The send action is obvious, but no additional behavioral context is given.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the primary action and then clarifies the parameter format. No redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-parameter send tool, the description covers the most complex aspect (recipient format) and is sufficient for correct usage. It could mention message length limits or error behavior, but these are not critical for a basic text send operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema descriptions are minimal, but the tool description adds significant clarity: it explains that 'to' accepts a raw phone number (digits, country code, no +) or JID, and provides explicit JID examples for individuals and groups. This goes beyond the schema and is essential for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Send a WhatsApp text message' uses a specific verb and resource, clearly distinguishing it from the sibling tool whatsapp_send_image. It unambiguously states the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies text-message usage but does not explicitly state when to use this tool vs alternatives. It provides no exclusions or alternatives, so the agent must infer from the word 'text'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send an image from a local absolute file path. The file must exist and be a valid image (jpg, png, gif, webp, etc.).
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Phone number (digits only, with country code) or a full JID. | |
| caption | No | Optional caption text to accompany the image. | |
| imagePath | Yes | Absolute path to the image file on disk. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It adds useful context about file requirements (absolute path, valid image types) but does not mention what happens on invalid input, whether the operation is blocking, or any side effects beyond 'sending' an image. This is a basic disclosure, not a rich one.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core action in the first sentence, and the second sentence adds a necessary precondition. Every word is useful, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description covers the main purpose, the key prerequisite, and all parameters are well-documented in the schema. It lacks information about return values or error handling, but that is not critical for this straightforward send action. A brief note on when to use this versus whatsapp_send would improve completeness, but the current level is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds minimal meaning beyond the schema: it reiterates 'local absolute file path' and lists valid image formats (jpg, png, gif, webp). This is a slight enhancement but does not fundamentally improve parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action: sending an image from a local absolute file path. The verb 'send' and resource 'image' are specific, and the source path is explicitly mentioned. It distinguishes itself from sibling tools like whatsapp_send (likely for text) and whatsapp_status (status updates).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the use case is sending images, and it provides a prerequisite (file must exist and be valid). However, it does not explicitly mention when not to use it or point to alternatives like whatsapp_send for text messages, which would warrant a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the WhatsApp connection status: whether connected, whether pairing (QR scan) is needed, the bot's own JID, and how many messages are buffered.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool is a status getter and lists the specific return fields, implying a read-only, non-destructive operation. This is sufficient for a status check, though it does not mention potential side effects like rate limits or connection resets, which would justify a higher score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the action ('Get') and the resource ('WhatsApp connection status'), followed by specific details. Every word earns its place, and there is no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has no parameters and no output schema, the description fully explains what the tool does and what it returns. It covers the essential information needed for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description does not need to explain parameter syntax or semantics, as there are none. It adds value by clarifying what the output contains, which is more relevant for a no-parameter status tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Get the WhatsApp connection status' and specifies the exact pieces of information it retrieves (connected, pairing, bot JID, buffered messages). This distinguishes it from sibling tools like whatsapp_send or whatsapp_list_chats, which handle different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that this tool is for checking connection status, and the sibling tool names make it obvious when to use it versus alternatives. However, it does not explicitly mention when not to use it or name alternatives, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool addresses a distinct concern: connection status, sending text, sending images, listing chats, and retrieving messages. There is no overlap in purpose, so an agent can reliably select the correct tool for a given task.
Tool names uniformly use the whatsapp_ prefix and mostly follow a verb_noun pattern (whatsapp_send, whatsapp_list_chats, whatsapp_get_messages). The only exception is whatsapp_status, which could be interpreted as a status check rather than a verb action, but the pattern is otherwise predictable.
Five tools is well-scoped for a WhatsApp bot server: covering status, messaging, and chat listing without unnecessary bloat. Each tool has a clear role and none are redundant.
The set covers core lifecycle needs: check connectivity, send text, send images, list chats, and read incoming messages. Minor gaps exist, such as sending other media types or marking messages as read, but these are not critical for typical usage.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Give your AI agents a real WhatsApp number to send and receive messages.
Connect a personal/Business WhatsApp account via QR pairing (multi-device, like WhatsApp Web). Send
WhatsApp for your app or AI agent over OAuth2 — the same connections WASync runs inside your CRM.
WhatsApp CRM for AI agents: search contacts, read chats, manage the sales pipeline, send messages.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/RicSchonfelder/whatsapp-hermes'
If you have feedback or need assistance with the MCP directory API, please join our Discord server