{
  "markdown": "# tgden — Telegram catalog as an MCP server + free API\n\n**A live index of what exists *on* Telegram: 1.2M+ channels, 245k+ group chats, 160k+ bots,\n4.9M+ indexed posts.** No Telegram account. No API key. No install. CORS enabled — it runs\nfrom a browser tab as happily as from a server.\n\n- **MCP endpoint** — `https://tgden.com/api/mcp`\n- **REST API** — `https://tgden.com/api/catalog`\n- **Human UI** — [tgden.com](https://tgden.com) · **Docs** — [tgden.com/en/api-docs](https://tgden.com/en/api-docs)\n\n---\n\n## Why another Telegram MCP server?\n\nEvery other Telegram MCP server connects to **your** Telegram account — you hand it an API\nhash, a phone number or a bot token, and it reads *your* dialogs, sends *your* messages,\nmanages *your* groups. Useful, but it can only ever see what you already have access to.\n\nThis one is the opposite. It's a **public catalog**, so it answers the question none of the\nothers can:\n\n> *\"What Telegram channels and groups exist about X, and which are worth joining?\"*\n\n|                            | account-based Telegram MCP        | **tgden MCP**                         |\n| -------------------------- | --------------------------------- | ------------------------------------- |\n| Credentials required       | API ID/hash, phone or bot token   | **none**                              |\n| Install                    | local process (Python/Go/Node)    | **none — a hosted HTTP URL**          |\n| Can see                    | chats you already joined          | **1.6M+ public entities you haven't** |\n| Answers *\"what exists?\"*   | no                                | **yes**                               |\n| Can act on your account    | yes                               | no — **read-only by design**          |\n\nBecause it never touches an account, there's nothing to leak and nothing to get banned.\n\n---\n\n## Quick start\n\n**Claude Code**\n\n```bash\nclaude mcp add --transport http tgden https://tgden.com/api/mcp\n```\n\nListed in the [official MCP Registry](https://registry.modelcontextprotocol.io) as\n`io.github.JustJuice55/telegram-catalog` — clients that browse the registry find it under\n*telegram*.\n\n**Claude Desktop · Cursor · any MCP client** — add to your MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"tgden\": {\n      \"type\": \"http\",\n      \"url\": \"https://tgden.com/api/mcp\"\n    }\n  }\n}\n```\n\nThat's the entire setup: streamable HTTP transport, stateless, no auth handshake.\n\n**Check it by hand:**\n\n```bash\ncurl -s https://tgden.com/api/mcp \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}' | jq '.result.tools[].name'\n```\n\n### Tools\n\n| Tool | What it answers |\n| ---- | --------------- |\n| `search_telegram` | Full-text search across channels, group chats and bots — with subscriber/member counts, categories and trust scores. |\n| `best_channels_by_category` | *\"Best Telegram channels for crypto / AI / news / gaming…\"* — ranked by subscribers. |\n| `channel_stats` | Everything known about one channel, by `@username`. |\n| `search_posts` | Full-text search over recent posts — what channels actually **said**, not just their bio. |\n| `market_listings` | Real classified listings (rent, sale, services, jobs) parsed from regional Telegram groups across 🇦🇪 🇹🇷 🇹🇭 🇻🇳 🇬🇪 🇺🇸. |\n| `market_stats` | Listing totals by country and type. |\n\n### Resources\n\n| URI | Contents |\n| --- | -------- |\n| `tgden://catalog/top-channels` | Top-100 channels by subscribers. |\n| `tgden://catalog/categories` | Full category taxonomy with channel counts. |\n| `tgden://market/listings-latest` | The 100 freshest marketplace listings. |\n| `tgden://market/stats` | Marketplace totals by country and type. |\n\n---\n\n## Free REST API (no key either)\n\nTelegram has no official public search. Finding a channel, a live discussion group or a bot\nby topic means guessing usernames or trusting closed directories. If you don't speak MCP,\nthe same catalog is plain HTTP.\n\n### `GET /api/catalog` — search\n\n| Param   | Type   | Default | Notes                                            |\n|---------|--------|---------|--------------------------------------------------|\n| `q`     | string | —       | Free-text query (title, username, topic)         |\n| `limit` | int    | `20`    | Max results to return                            |\n| `type`  | string | all     | `channel` · `chat` · `bot` (omit for everything) |\n\n```bash\ncurl \"https://tgden.com/api/catalog?q=crypto&type=channel&limit=3\"\n```\n\n```json\n{\n  \"items\": [\n    {\n      \"id\": \"6ec0407a-4f5e-4a86-9154-f42481bc9413\",\n      \"telegram_id\": 2075341442,\n      \"username\": \"hamster_kombat\",\n      \"title\": \"Hamster Kombat Announcement\",\n      \"is_private\": false,\n      \"avatar_url\": \"https://cdn4.telesco.pe/file/…\"\n    }\n  ]\n}\n```\n\n### Call it from the browser\n\n`Access-Control-Allow-Origin: *` is set on both read-only endpoints, so there is no proxy\nstep: paste this into any page's devtools console (or a CodePen) and it answers.\n\n```js\nconst r = await fetch(\"https://tgden.com/api/catalog?q=crypto&type=channel&limit=3\");\nconsole.table((await r.json()).items);\n```\n\nRate limit is shared and fair-use (~200 requests / 10s per IP). No key, no signup, no CORS\nproxy, no `Access-Control-Allow-Credentials` — nothing of yours is ever sent.\n\n### `GET /api/suggest` — instant autocomplete\n\nGrouped, ranked suggestions as-you-type. Good for search boxes and agent tool-use.\n\n```bash\ncurl \"https://tgden.com/api/suggest?q=btc\"\n```\n\n```json\n{\n  \"groups\": [\n    {\n      \"key\": \"chats\",\n      \"label\": { \"en\": \"live chats\", \"ru\": \"живые чаты\" },\n      \"items\": [\n        { \"label\": \"BTC Times Discussion\", \"sub\": \"221 members\",\n          \"href\": \"/en/chat/thebtctimes\", \"kind\": \"chat\", \"username\": \"thebtctimes\" }\n      ]\n    }\n  ]\n}\n```\n\nRunnable examples: [shell](examples/search.sh) · [Python](examples/search.py) · [JavaScript](examples/search.js).\n\n---\n\n## Limits — published, because hidden limits are worse than low ones\n\n| Surface | Limit |\n| ------- | ----- |\n| REST (`/api/catalog`, `/api/suggest`) | ~200 requests / 10s per IP, shared fair-use |\n| MCP (`/api/mcp`) | 240 calls / hour per IP |\n| Auth | none — no key, no signup, no email |\n| Cost | free |\n\nVerified search-engine and AI crawlers are excluded from the shared limit.\n\nWe treat these as a contract: when they change, we announce it here and in\n[the docs](https://tgden.com/en/api-docs). **No silent throttling.** Need guaranteed\nthroughput or a bulk export for something real? Open an issue, or reach us via\n[@tgden_bot](https://t.me/tgden_bot).\n\n---\n\n## About the data\n\nParsed continuously from Telegram's public surfaces — **fresher than any LLM training set**,\nwhich is most of the point of exposing it over MCP.\n\n| | |\n| --- | --- |\n| Channels | 1,298,868 |\n| Group chats | 282,719 |\n| Bots | 157,909 |\n| Indexed posts | 4,955,162 |\n| Marketplace listings | 34,862 |\n\n*Census 06.08.2026. The MCP server reports these totals **live**, so what your agent sees is\ncurrent — not whatever was true when this file was written.*\n\nPublic data only: channels, groups and bots that are already publicly listed or linked.\nNo private groups, no archives from closed communities, no personal data.\n\n---\n\n## Use cases\n\n- **Agent tool-use** — give an agent real Telegram discovery in one config line.\n- **Research** — map communities, track niches, study the open Telegram graph.\n- **Discovery bots** — recommend channels and chats by topic.\n- **Market intel** — what's being rented, sold and offered in regional Telegram economies.\n\nMachine-readable site summary for AI crawlers: <https://tgden.com/llms.txt>\n\n## License\n\n[MIT](LICENSE) — do what you want, no warranty. Data is public Telegram metadata.\n\n---\n\n<sub>Maintained by [tgden.com](https://tgden.com). Not affiliated with Telegram FZ-LLC.\nIndexes public `t.me` links only.</sub>\n",
  "bytes": 7821,
  "sha": "6371184188deefc0ec328475faaa27c26b569f9d1ee52b0000e546db26d23413",
  "repo_slug": "justjuice55/tgden-api",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_justjuice55_telegram_catalog_5a05bee6/readme"
}