grouppulse

grouppulse

設定するキーなしで利用できる、Telegram 公開グループの統計情報です。grouppulse は Limzo の公開 API を利用します。この API は、Telegram の公開グループに関する読み取り専用の集計統計情報を公開しています。グループのアクティブ度、最もアクティブなメンバー、レベルの構成、授与されたアワード、モデレーションの概要を確認できます。ここではアカウントは不要で、上流のデータにメンバーのメッセージがそのまま含まれることはありません。集計データとランキングのみなので、grouppulse が受け渡すデータも同じ性質を引き継ぎます。

データからわかることの大部分は、次の3つの質問でカバーできます。あるトピックや言語に関連する公開グループはどれか、特定のグループの状況はどうか、ネットワーク全体の状況はどうか、という質問です。

設定

• LIMZO_BASE_URL（任意）— API のベース URL です。 デフォルトは https://limzo.com です。

以上です。API キーはありません。すべてのエンドポイントが公開されており、読み取り専用です。

ツール

• list_groups — 公開グループのディレクトリを検索または閲覧します。各項目にはスラッグ、タイトル、メンバー数、言語が含まれます。すべての引数は任意です。query（グループのタイトル、ユーザー名、スラッグ、説明に対して照合するキーワード）、language（fa や es などの ISO 639-1 コード）、limit（返すグループ数）を指定できます。何も指定しない場合は、上位のグループが一覧表示されます。
• get_group_stats — slug（limzo.com/s/<slug> ページの末尾の部分）で指定したグループの公開統計情報を取得します。アクティビティ、上位メンバー、レベル、アワード、モデレーションの概要に加え、上流に十分なデータがある場合は、グループの雰囲気や言語の内訳も返します。任意の range で統計期間を指定できます。7d（デフォルト）、30d、all のいずれかを指定します。より長い期間のデータには、上流でグループの有料プランが必要です。無料グループの場合、結果は通知なく 7d にフォールバックします。返された range ブロックで確認できます。
• get_global_stats — すべての公開グループを対象としたネットワーク全体の合計値と、現在の上位グループを取得します。

知っておくとよい動作：

• 2xx の応答は、API が返したものとまったく同じ内容で返されます。受け渡しの際に、何かが削除、改名、要約されることはありません。
• それ以外の応答では grouppulse error: HTTP <status> が返されます。たとえば、存在しないスラッグの場合は 404、グループの公開ページが無効になっている場合は 403、統計情報が削除されている場合は 410、上流で許可されている頻度（毎秒5リクエスト）を超えてポーリングした場合は 429 です。API に到達できない場合は grouppulse error: unreachable が返されます。これらのエラー文字列は、この再実装独自のものです。
• 上流は、クライアントにキャッシュヘッダーを尊重するよう求めています（応答は30分間キャッシュされます）。統計情報はゆっくり変化するため、ポーリングが必要になることはほとんどありません。

エンドポイントの出典

ベンダーが公開している OpenAPI ドキュメントで、エンドポイント、通信時のパラメーター名、期間の値が特定されています。元の MCP プロジェクトの README で、3つのツールが特定されています。MCP 層の引数名は、特定済みの通信パラメーターに対応付けた再構成名です。

• GET <base>/api/public/groups。設定されている場合は q、lang、limit を指定します（list_groups で使用。MCP の引数は query、language、limit です）。
• GET <base>/api/public/{slug}。設定されている場合は range を指定します（get_group_stats で使用。/s/{slug}.json ページのルートも同じペイロードを返し、/api/public/ パスが API ルートです）。
• GET <base>/api/public/global-stats（get_global_stats で使用）。

slug のパスセグメントは URL エンコードされます。

CLI

各ツールは、1つの JSON 引数文字列を受け取るサブコマンドです。

npx @reneturcios/grouppulse list_groups '{"language":"es","limit":5}'
npx @reneturcios/grouppulse get_group_stats '{"slug":"hipo"}'
npx @reneturcios/grouppulse get_group_stats '{"slug":"hipo","range":"30d"}'
npx @reneturcios/grouppulse get_global_stats '{}'
npx @reneturcios/grouppulse --version

出力はツールの結果テキスト（成功時は上流の本文）です。終了コード：成功時は 0、実行時エラー時は 1、使用方法のエラー時は 2 です。

MCP サーバー

npx -y @reneturcios/grouppulse mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "grouppulse": {
      "command": "npx",
      "args": ["-y", "@reneturcios/grouppulse", "mcp"]
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/grouppulse
docker run --rm ghcr.io/cloudcorprecords/grouppulse get_global_stats '{}'

開発

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (fake fetch only, no network)
npm run dev     # run the CLI from source

ライセンス

MIT — Copyright (c) 2026 Rene Turcios