hellohop

hellohop-mcp

HelloHop 是面向开发者的独立 WhatsApp API：发送和接收消息、自动管理群组和社群，以及获取带签名的 Webhook，每个号码每月 25 美元起，并提供免费的沙盒。

这是 HelloHop MCP 服务。它让 MCP 客户端（例如 Claude Desktop、Claude Code 或 Cursor）能够使用公共 API 中的一个渠道：读取渠道状态、它已观察到的聊天、近期消息、群组和社群，以及联系人。发送内容（文本、通过 URL 发送媒体、投票、反应）默认关闭，仅在你启用后可用。文档：https://hellohop.app/docs/mcp。HelloHop 与 WhatsApp 或 Meta 没有关联，也未获其认可。

安装

需要 Node.js 22 或更高版本。使用 npx 运行，无需单独安装：

npx -y hellohop-mcp

配置完成后，MCP 客户端会为你启动该服务（见下文的 Claude Desktop 和 Claude Code）。服务会从环境变量中读取设置，变量列表见“环境变量”部分。

工具

工具	请求	备注
channel_status	GET {base}/sessions/{channel}	include_safety: true 还会读取 GET {base}/sessions/{channel}/safety。
list_chats	GET {base}/sessions/{channel}/chats	从频道自己的日志中获取最多 100 个聊天。
read_messages	GET {base}/sessions/{channel}/chats/{chat}/messages	最多获取 limit 条消息（默认 50，最多 500）；next_before 会作为 before 向前翻页。chat 按原样传递，例如 [email protected]。
list_groups	GET {base}/sessions/{channel}/groups	会向 WhatsApp 发起请求；不要轮询（被限流的号码会返回 429 whatsapp_rate_limited）。
get_group	GET {base}/sessions/{channel}/groups/{group}	会向 WhatsApp 发起请求。
get_community	GET {base}/sessions/{channel}/communities/{community}	会向 WhatsApp 发起请求。
list_community_subgroups	GET {base}/sessions/{channel}/communities/{community}/subgroups	会向 WhatsApp 发起请求。
get_contact	GET {base}/sessions/{channel}/contacts/{who}	频道存储的联系人条目；不会向 WhatsApp 发起请求。
send_text	POST {base}/sessions/{channel}/messages/text	仅当 GATEWAY_ALLOW_SEND=1 时可用。请求体为 {to, text}，如有提供，还包括 quoted。
send_media	POST {base}/sessions/{channel}/messages/{kind}	仅当 GATEWAY_ALLOW_SEND=1 时可用。kind 为 image、video、audio、voice 或 document；请求体为 {to, url}，如有提供，还包括 caption、filename、mime_type。网关会获取该 URL。
send_poll	POST {base}/sessions/{channel}/messages/poll	仅当 GATEWAY_ALLOW_SEND=1 时可用。请求体为 {to, question, options}（2 至 12 个选项），如有提供，还包括 multiple。
react	PUT {base}/sessions/{channel}/messages/{message_id}/reaction	仅当 GATEWAY_ALLOW_SEND=1 时可用。请求体为 {emoji}。
unreact	DELETE {base}/sessions/{channel}/messages/{message_id}/reaction	仅当 GATEWAY_ALLOW_SEND=1 时可用。无请求体。
delete_message	DELETE {base}/sessions/{channel}/messages/{message_id}	仅当 GATEWAY_ALLOW_SEND=1 时可用。无请求体。在 48 小时内删除该号码发送的消息，且对所有人生效。

有意不提供：群组和社区邀请链接（Agent 可能会把公开邀请链接粘贴到聊天中）、媒体下载（返回字节而非 JSON）以及 webhook 配置。

get_group 会返回群组参与者列表。这属于你自己的群组数据，因此会像其他工具结果一样进入 MCP 客户端的上下文。只有在你信任该客户端处理这些成员身份信息时，才使用此工具。

公共 API 在读取对话时只转发 limit（1 至 500）和 before，因此 read_messages 使用这两个参数翻页，其他查询字符串都不会传递给 API。其他列表工具不接受分页参数。

聊天标识会直接放入 URL 路径，不进行百分号编码，因为 API 会拒绝任何包含 % 的路径。若聊天标识包含字母、数字和 @ . : _ + - 以外的字符，则会在发起请求前被拒绝。

每个请求都会发送 Authorization: Bearer <token>。成功响应以 JSON 文本形式返回。HTTP 错误会作为工具错误返回，其中包含 status、code 和 error；如果 API 返回了 retry_after（以及 window、resets_at、ambiguous、id），错误中也会包含这些字段。所有返回字符串中的令牌都会被隐藏，成功响应正文也不例外。系统不会自动重试；遇到重定向时会直接拒绝，而不会跟随。

环境

变量	必需	含义
GATEWAY_API_URL	否	API 基础 URL。默认为 https://api.hellohop.app/v1，即公共 API。必须使用 https（仅 localhost 接受 http）。
GATEWAY_API_TOKEN	是	该频道的 API 令牌。此令牌绝不会被记录到日志中。
GATEWAY_CHANNEL_ID	是	此令牌所属的频道 ID。
GATEWAY_ALLOW_SEND	否	设置为恰好 1 或 true 以启用发送工具（send_text、send_media、send_poll、react、unreact、delete_message）。任何其他值或未设置时，这些工具都不会启用。

如果缺少必需变量，服务会将原因写入 stderr，并以状态码 1 退出。

默认关闭发送功能

未设置 GATEWAY_ALLOW_SEND=1 时，不会注册任何发送工具：客户端无法看到或调用这些工具，服务也绝不会联系发送端点。启用后，每次调用都会通过已关联的号码发送一条真实的 WhatsApp 消息（包括添加反应、移除反应和删除消息），并计入频道的每日发送上限（如果有；运营人员可以将频道设为不受上限限制）。

发送可能成功，但不会返回成功提示

如果 send_text 失败时消息仍有可能已发送，则会返回 delivery: "unknown"：例如未收到响应、API 返回 ambiguous: true（504 send_unconfirmed，其中包含已记录该请求的行的 id），或返回任何其他 502 或 504。不要再次发送。请先通过 read_messages 检查该聊天。再次发送可能导致同一条消息被发送给真实用户两次。

提示词注入：同时读取和发送会让陌生人操控发送内容

read_messages 会将第三方（即任何能够向该号码发送消息的人）撰写的文本放入模型的上下文中。如果同一服务还启用了 GATEWAY_ALLOW_SEND=1，这些文本就可能指示模型向任何人发送任何内容。这无法通过信任客户端或使用者来解决：指令来自正在读取的消息。

将读取和发送配置为两个独立的客户端配置：

• 只读配置，不设置 GATEWAY_ALLOW_SEND，用于任何会读取消息的场景；
• 发送配置，设置 GATEWAY_ALLOW_SEND=1，仅在需要发送的会话中启用，并由人员审核每次 send_text 调用的 to 和 text 后批准。

发送配置仍会注册读取工具，因此一旦使用该配置的会话读取消息，就会暴露于风险之中。除非你信任所有能够向该号码发送消息的人，否则不要在该会话中使用 read_messages。

Claude Desktop

在 claude_desktop_config.json 的 mcpServers 中添加一项：

{
  "mcpServers": {
    "hellohop-mcp": {
      "command": "npx",
      "args": ["-y", "hellohop-mcp"],
      "env": {
        "GATEWAY_API_TOKEN": "<CHANNEL_TOKEN>",
        "GATEWAY_CHANNEL_ID": "<CHANNEL_ID>"
      }
    }
  }
}

在 env 中添加 "GATEWAY_ALLOW_SEND": "1" 以启用发送功能。编辑文件后，重启 Claude Desktop。

Claude Code

claude mcp add hellohop-mcp \
  -e GATEWAY_API_TOKEN=<CHANNEL_TOKEN> \
  -e GATEWAY_CHANNEL_ID=<CHANNEL_ID> \
  -- npx -y hellohop-mcp

在 -- 前添加 -e GATEWAY_ALLOW_SEND=1 以启用发送功能。

这两个客户端都会将令牌以纯文本形式存储在其配置文件中。请使用频道自身的令牌，切勿使用运营人员凭据。

Cursor

在 ~/.cursor/mcp.json（或项目中的 .cursor/mcp.json）添加相同的配置项：

{
  "mcpServers": {
    "hellohop-mcp": {
      "command": "npx",
      "args": ["-y", "hellohop-mcp"],
      "env": {
        "GATEWAY_API_TOKEN": "<CHANNEL_TOKEN>",
        "GATEWAY_CHANNEL_ID": "<CHANNEL_ID>"
      }
    }
  }
}

除非在 env 中添加 "GATEWAY_ALLOW_SEND": "1"，否则发送功能会保持关闭。

请求示例

连接后，可以用自然语言向助手提问。例如：

• “我的频道状态如何？”（调用 channel_status）
• “显示我与 [email protected] 的聊天中的最近 20 条消息。”（调用 read_messages）
• “列出这个号码所在的群组。”（调用 list_groups）

许可证

MIT。完整文档：https://hellohop.app/docs/mcp