grouppulse

grouppulse

公开 Telegram 群组统计，无需设置密钥。grouppulse 调用 Limzo 公共 API，该 API 发布公开 Telegram 群组的只读汇总统计：群组的活跃程度、最活跃的成员、等级体系、颁发的奖项，以及管理摘要。这里的所有内容都无需账号，而且上游数据从不包含成员消息原文——只有汇总数据和排行榜——因此 grouppulse 传递的数据也具有这一特性。

数据可以回答的问题大多归为三类：某个主题或语言下有哪些公开群组，某个特定群组的情况如何，以及整个网络的总体情况如何。

配置

• LIMZO_BASE_URL（可选）— API 基础 URL。 默认为 https://limzo.com。

就这些。没有 API 密钥：所有端点都是公开且只读的。

工具

• list_groups — 搜索或浏览公开群组目录。 每个条目都包含其 slug、标题、成员数和语言。所有参数均为可选：query（匹配群组标题、用户名、slug 和描述的关键词）、 language（ISO 639-1 代码，例如 fa 或 es），以及 limit（返回的群组数量）。 全部省略即可列出排名靠前的群组。
• get_group_stats — 获取某个群组的完整公开统计数据，按其 slug 指定（即其 limzo.com/s/<slug> 页面路径的最后一部分）。结果涵盖活跃度、顶级成员、等级、奖项和管理摘要；如果上游有足够的数据，还会包含群组的情绪和语言分布。 可选参数 range 用于选择统计时间范围： 7d（默认值）、30d 或 all；较长的时间范围要求该群组在上游拥有付费计划，对于免费群组，结果会静默回退到 7d，可通过返回的 range 块查看。
• get_global_stats — 所有公开群组的全网总计数据，以及当前排名靠前的群组。

需要了解的行为：

• 2xx 响应会原样返回 API 的内容：传递过程中不会删减、重命名或汇总任何内容。
• 其他任何响应都会报错： grouppulse error: HTTP <status> — 例如，未知 slug 会返回 404，群组的公开页面已禁用时会返回 403，统计数据已删除时会返回 410，请求频率超过上游限制（每秒 5 次）时会返回 429。API 无法访问时会报错 grouppulse error: unreachable。这些错误字符串由此重建版本自行定义。
• 上游要求客户端遵守其缓存标头（响应会缓存 30 分钟）；统计数据变化缓慢，因此通常无需频繁轮询。

端点来源

供应商发布的 OpenAPI 文档明确规定了端点、网络参数名称和范围值；原 MCP 项目的 README 则明确规定了这三个工具。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

每个工具都是一个子命令，接受一个 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