Grouppulse MCP Server

grouppulse

Public Telegram group statistics, with no key to set up. grouppulse talks to the Limzo public API, which publishes read-only aggregate statistics for public Telegram groups: how active a group is, who its most active members are, how its level ladder looks, what awards it has handed out, and a moderation summary. Nothing here needs an account, and the upstream data never contains verbatim member messages — only aggregates and leaderboards — so what grouppulse passes through inherits that property.

Three questions cover most of what the data can answer: which public groups exist around a topic or a language, how one particular group is doing, and how the whole network looks in total.

Configuration

• LIMZO_BASE_URL (optional) — API base URL. Defaults to https://limzo.com.

That is all. There is no API key: every endpoint is public and read-only.

Tools

• list_groups — search or browse the public group directory. Each entry carries its slug, title, member count and language. All arguments are optional: query (a keyword matched against group titles, usernames, slugs and descriptions), language (an ISO 639-1 code such as fa or es), and limit (how many groups to return). Omit everything to list the top groups.
• get_group_stats — full public stats for one group, by its slug (the last part of its limzo.com/s/<slug> page). The result covers activity, top members, levels, awards and a moderation summary, plus the group's mood and language mix when the upstream has enough signal. The optional range picks the stats window: 7d (the default), 30d or all; the longer windows need the group's paid plan upstream, and on a free group the answer silently falls back to 7d, which you can spot in the returned range block.
• get_global_stats — network-wide totals across all public groups, plus the current top groups.

Behaviour worth knowing:

• A 2xx answer comes back exactly as the API returned it: nothing is trimmed, renamed or summarised on the way through.
• Any other reply fails with grouppulse error: HTTP <status> — for example a 404 for an unknown slug, a 403 when a group's public page is disabled, a 410 when its stats were deleted, or a 429 when you poll faster than the upstream allows (5 requests per second). An unreachable API fails with grouppulse error: unreachable. These error strings are this rebuild's own.
• The upstream asks clients to respect its cache headers (responses are cached for 30 minutes); stats move slowly, so there is rarely a reason to poll.

Endpoint provenance

The vendor's published OpenAPI document pins the endpoints, the wire parameter names and the range values; the original MCP project's README pins the three tools. The MCP-layer argument names are labelled reconstructions mapped onto the pinned wire parameters:

• GET <base>/api/public/groups with q, lang and limit when set (used by list_groups; the MCP arguments are query, language and limit).
• GET <base>/api/public/{slug} with range when set (used by get_group_stats; the /s/{slug}.json page route carries the same payload, and the /api/public/ path is the API route).
• GET <base>/api/public/global-stats (used by get_global_stats).

The slug path segment is URL-encoded.

CLI

Each tool is a subcommand taking one JSON argument string:

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

Output is the tool's result text (the upstream body on success). Exit codes: 0 on success, 1 on a runtime error, 2 on a usage error.

MCP server

npx -y @reneturcios/grouppulse mcp

MCP client config:

{
  "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 '{}'

Development

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

License

MIT — Copyright (c) 2026 Rene Turcios