hellohop

hellohop-mcp

HelloHop は、開発者向けの独立した WhatsApp API です。メッセージの送受信、グループやコミュニティの自動化、署名付き Webhook に対応しており、料金は 1 番号あたり月額 25 ドルから、無料のサンドボックスも利用できます。

これは HelloHop の MCP サーバーです。MCP クライアント（Claude Desktop、Claude Code、Cursor など）から、公開 API の 1 つのチャネルを操作できます。チャネルのステータス、チャネルが確認したチャット、最近のメッセージ、グループとコミュニティ、連絡先を確認できます。メッセージの送信（テキスト、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時間以内であれば全員のチャットから削除します。

意図的に公開していない機能：グループとコミュニティの招待リンク（エージェントがチャットに公開招待リンクを貼り付けるおそれがあります）、メディアのダウンロード（JSON ではなくバイトデータ）、Webhook の設定。

get_group はグループの参加者リストを返します。これは自身のグループデータであるため、他のツールの結果と同様に MCP クライアントのコンテキストに取り込まれます。メンバーの身元情報を扱うクライアントに対してのみ使用してください。

公開 API で会話の読み取り時に転送されるのは limit（1～500）と before のみです。そのため、read_messages はこれら2つを使ってページングし、それ以外のクエリ文字列は API に送信しません。他の一覧取得ツールはページングパラメーターを受け取りません。

API が % を含むパスを拒否するため、チャットはパーセントエンコードせずに URL パスへ送信されます。英字、数字、@ . : _ + - 以外の文字を含むチャットは、リクエストを行う前に拒否されます。

すべてのリクエストに Authorization: Bearer <token> を含めます。成功したレスポンスは JSON テキストとして返されます。HTTP エラーは status、code、error を含むツールエラーとして返されます。API が値を返した場合は、retry_after（および window、resets_at、ambiguous、id）も含まれます。成功レスポンスの本文を含め、返されるすべての文字列からトークンはマスキングされます。自動再試行は行われず、リダイレクトは追従せずに拒否されます。

環境

変数	必須	意味
GATEWAY_API_URL	いいえ	API のベース URL です。デフォルトは公開 API の https://api.hellohop.app/v1 です。https が必須です（localhost の場合に限り http も使用できます）。
GATEWAY_API_TOKEN	はい	チャネルの API トークンです。ログに記録されることはありません。
GATEWAY_CHANNEL_ID	はい	トークンが属するチャネル ID です。
GATEWAY_ALLOW_SEND	いいえ	送信ツール（send_text、send_media、send_poll、react、unreact、delete_message）を有効にするには、正確に 1 または true を設定します。それ以外の値、または未設定の場合、送信ツールは無効のままです。

必須の変数が設定されていない場合、サーバーはその理由を stderr に出力し、ステータス 1 で終了します。

送信はデフォルトで無効です

GATEWAY_ALLOW_SEND=1 を設定しない限り、送信ツールは登録されません。クライアントからツールを確認したり呼び出したりすることはできず、サーバーが送信エンドポイントにアクセスすることもありません。有効にすると、呼び出しのたびにリンク済みの番号から実際の WhatsApp メッセージが送信されます（リアクション、その取り消し、メッセージの削除も含みます）。チャネルに 1 日あたりの送信上限がある場合、各呼び出しはその上限の 1 件としてカウントされます（運用者はチャネルを上限の対象外にできます）。

送信が成功していても、そのように通知されない場合があります

メッセージが送信された可能性がある場合、send_text の失敗には delivery: "unknown" が含まれます。これは、応答が届かなかった場合、API が ambiguous: true（ログに記録された行の id を含む 504 send_unconfirmed）を返した場合、またはその他の 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