HelloHop is an independent WhatsApp API for developers: send and receive messages, automate groups and communities, and get signed webhooks, from $25 per number per month with a free sandbox.
This is the HelloHop MCP server. It lets an MCP client (for example Claude Desktop, Claude Code or Cursor) work with one channel of the public API: read the channel's status, the chats it has observed, recent messages, its groups and communities, and a contact. Sending (a text, media by URL, a poll, a reaction) is and available only when you turn it on. Docs: . HelloHop is not affiliated with or endorsed by WhatsApp or Meta.
Read WhatsApp chats and groups, and send messages when allowed, through the HelloHop API.
Requires Node.js 22 or later. Run it with npx, no separate install step:
npx -y hellohop-mcp
Your MCP client starts the server for you once it is configured (see Claude Desktop and Claude Code below). The server reads its settings from the environment variables listed under Environment.
Tools
Tool
Request
Notes
channel_status
GET {base}/sessions/{channel}
include_safety: true also reads GET {base}/sessions/{channel}/safety.
list_chats
GET {base}/sessions/{channel}/chats
Up to 100 chats from the channel's own log.
read_messages
GET {base}/sessions/{channel}/chats/{chat}/messages
Up to limit messages (default 50, at most 500); next_before goes back as before. chat is sent as written, for example [email protected].
list_groups
GET {base}/sessions/{channel}/groups
Asks WhatsApp; do not poll (a throttled number answers 429 whatsapp_rate_limited).
get_group
GET {base}/sessions/{channel}/groups/{group}
Asks WhatsApp.
get_community
GET {base}/sessions/{channel}/communities/{community}
Asks WhatsApp.
list_community_subgroups
GET {base}/sessions/{channel}/communities/{community}/subgroups
Asks WhatsApp.
get_contact
GET {base}/sessions/{channel}/contacts/{who}
The channel's stored contact entry; does not ask WhatsApp.
send_text
POST {base}/sessions/{channel}/messages/text
Only when GATEWAY_ALLOW_SEND=1. Body {to, text}, plus quoted if given.
send_media
POST {base}/sessions/{channel}/messages/{kind}
Only when GATEWAY_ALLOW_SEND=1. kind is image, video, audio, voice or document; body {to, url} plus caption, filename, mime_type if given. The gateway fetches the URL.
send_poll
POST {base}/sessions/{channel}/messages/poll
Only when GATEWAY_ALLOW_SEND=1. Body {to, question, options} (2 to 12), plus multiple if given.
react
PUT {base}/sessions/{channel}/messages/{message_id}/reaction
Only when GATEWAY_ALLOW_SEND=1. No body. Deletes for everyone a message this number sent, within 48 hours.
Not exposed, on purpose: group and community invite links (an agent could paste an open invite into a chat), media download (bytes, not JSON) and webhook configuration.
get_group returns the group's participant list, which is your own group data, so it enters the MCP client's context like any other tool result. Use it only with a client you trust with those member identities.
The public API forwards only limit (1 to 500) and before on the conversation read, so read_messages pages with those two and no other query string reaches the API. The other list tools take no paging parameters.
A chat is sent in the URL path without percent-encoding, because the API refuses any path containing %. A chat containing anything other than letters, digits and @ . : _ + - is refused before a request is made.
Every request sends Authorization: Bearer <token>. A successful response is returned as JSON text. An HTTP error is returned as a tool error with status, code and error, plus retry_after (and window, resets_at, ambiguous, id) when the API sends them. The token is redacted from every string returned, success bodies included. Nothing is retried automatically, and a redirect is refused rather than followed.
Environment
Variable
Required
Meaning
GATEWAY_API_URL
no
Your API base. Defaults to https://api.hellohop.app/v1, the public API. Must be https (http is accepted only for localhost).
GATEWAY_API_TOKEN
yes
The channel's API token. It is never logged.
GATEWAY_CHANNEL_ID
yes
The channel ID the token belongs to.
GATEWAY_ALLOW_SEND
no
Set to exactly 1 or true to enable the send tools (send_text, send_media, send_poll, react, unreact, delete_message). Any other value, or unset, leaves them off.
If a required variable is missing the server writes the reason to stderr and exits with status 1.
Sending is off by default
Without GATEWAY_ALLOW_SEND=1 no send tool is registered: a client cannot see or call them, and the server never contacts a send endpoint. With it on, every call sends a real WhatsApp message from the linked number (a reaction, its removal and a delete included) and counts as one against the channel's daily send cap if it has one (an operator can exempt a channel from the cap).
A send can succeed without saying so
A failed send_text carries delivery: "unknown" when the message may have been sent anyway: no response arrived, the API answered ambiguous: true (a 504 send_unconfirmed, with the id of the row it logged), or the answer was any other 502 or 504. Do not send it again. Check read_messages for that chat first. Sending it again is how the same message reaches a real person twice.
Prompt injection: read and send together let strangers steer sends
read_messages puts text written by third parties, anyone who can message the number, into the model's context. With GATEWAY_ALLOW_SEND=1 in the same server, that text can instruct the model to send messages, to anyone, with any content. This is not solved by trusting the client or the person using it: the instructions come from the messages being read.
Run reading and sending as two separate client configurations:
a read-only entry, without GATEWAY_ALLOW_SEND, for anything that reads messages;
a send entry, with GATEWAY_ALLOW_SEND=1, enabled only in a session that needs to send, with every send_text call approved by a person who reads its to and text.
The send entry still registers the read tools, so a session using it is exposed the moment it reads messages. Keep that session away from read_messages unless you trust everyone who can message the number.
Claude Desktop
Add an entry to mcpServers in claude_desktop_config.json: