{"id":"987d8bb2-77c3-4aaf-9f40-2c7c5f4507ea","slug":"telegram-api-mcp","kind":"mcp","name":"telegram-api-mcp","summary":"Ultimate Telegram Bot API MCP server — full v9.6 coverage, meta-mode, rate limiting, circuit breaker. TypeScript.","owner":"timoncool","repoUrl":"https://github.com/timoncool/telegram-api-mcp","license":"MIT","licenseTier":"permissive","trust":"community","stars":32,"match":null,"fewStars":false,"format":"mcp","createdAt":"2026-04-04T01:26:09.000Z","addedAt":"2026-10-14T03:48:01.693Z","logoUrl":"https://avatars.githubusercontent.com/u/26026304?u=80e42553ce40521e94340bb41ba4f1c0351656b4&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["communication","cloud-infra","memory-knowledge"],"tags":["ai-tools","chatbot","claude","telegram","telegram-bot-api","typescript"],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-15T03:07:27.264Z","sample":false,"url":"https://conduits.dev/tools/telegram-api-mcp","language":"TypeScript","transports":["stdio"],"install":{"npm":"telegram-api-mcp"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"
\n\n# telegram-api-mcp\n\n**Ultimate MCP server for Telegram Bot API — 185 methods, full v10.2 coverage, rich messages, meta-mode, rate limiting, circuit breaker.**\n\n[](https://github.com/timoncool/telegram-api-mcp/stargazers)\n[](https://www.npmjs.com/package/telegram-api-mcp)\n[](LICENSE)\n[](https://core.telegram.org/bots/api)\n[](https://github.com/timoncool/trail-spec)\n\n
\n\n185/185 Bot API methods with Zod validation, token masking, tool annotations, and zero bloat (2 dependencies).\n\n## Features\n\n- **185/185 Bot API methods** — messages, media, polls, chats, forums, stickers, payments, business, stories, gifts, games, inline, managed bots\n- **Rich messages** — post up to 32768 characters with headings, tables, lists, collages, slideshows, footnotes and up to 50 inline media, instead of the 1024-character caption ceiling\n- **Bot API 10.2** (July 2026) — rich messages, ephemeral messages, live photos, guest mode, join-request queries, poll media\n- **`telegram_format` tool** — the server explains the exact shape of `rich_message`, `media`, `reply_markup`, `poll` and more *before* you send, so an agent never has to guess the syntax (also exposed as MCP resources under `telegram://format/…`)\n- **Meta-mode** — 2 tools instead of 185, saves ~99% context tokens\n- **Rate limiting** — global (30 req/sec) + per-chat (20 msg/min), token bucket with async mutex\n- **Circuit breaker** — 3-state (closed/open/half-open), auto-recovery\n- **Retry with backoff** — respects Telegram 429 `retry_after`, exponential backoff on 5xx\n- **Zod validation** — every parameter validated before hitting Telegram API\n- **Token masking** — bot token never appears in responses, logs, or error messages\n- **File upload security** — path traversal protection, configurable allowed directories\n- **Tool annotations** — all 185 methods annotated (readOnly, destructive, idempotent, openWorld)\n- **Docs mirror + audit** — `npm run docs:refresh` re-downloads the official spec, `npm run audit` fails if any method or parameter drifts from it\n- **Response truncation** — 100K char limit to prevent context overflow\n- **Zero bloat** — only 2 dependencies: `@modelcontextprotocol/sdk` + `zod`\n\n## Quick Start\n\n### Claude Code\n\n```bash\nclaude mcp add telegram -- npx telegram-api-mcp -e TELEGRAM_BOT_TOKEN=your_token\n```\n\nWith meta-mode (recommended for large conversations):\n\n```bash\nclaude mcp add telegram -- npx telegram-api-mcp \\\n -e TELEGRAM_BOT_TOKEN=your_token \\\n -e TELEGRAM_META_MODE=true\n```\n\n### Claude Desktop\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"telegram\": {\n \"command\": \"npx\",\n \"args\": [\"telegram-api-mcp\"],\n \"env\": {\n \"TELEGRAM_BOT_TOKEN\": \"your_token_from_botfather\"\n }\n }\n }\n}\n```\n\n### With default chat (skip chat_id in every call)\n\n```json\n{\n \"mcpServers\": {\n \"telegram\": {\n \"command\": \"npx\",\n \"args\": [\"telegram-api-mcp\"],\n \"env\": {\n \"TELEGRAM_BOT_TOKEN\": \"your_token\",\n \"TELEGRAM_DEFAULT_CHAT_ID\": \"-1001234567890\"\n }\n }\n }\n}\n```\n\n### From source\n\n```bash\ngit clone https://github.com/timoncool/telegram-api-mcp.git\ncd telegram-api-mcp\nnpm install && npm run build\nTELEGRAM_BOT_TOKEN=your_token node dist/index.js\n```\n\n## Environment Variables\n\n| Variable | Required | Default | Description |\n|----------|:---:|:---:|-------------|\n| `TELEGRAM_BOT_TOKEN` | **Yes** | — | Bot token from [@BotFather](https://t.me/BotFather) |\n| `TELEGRAM_DEFAULT_CHAT_ID` | No | — | Default chat ID for all tools |\n| `TELEGRAM_DEFAULT_THREAD_ID` | No | — | Default forum topic thread ID |\n| `TELEGRAM_META_MODE` | No | `false` | Use 2 meta-tools instead of 185 |\n| `TELEGRAM_GLOBAL_RATE_LIMIT` | No | `30` | Max requests/sec ([Telegram limit](https://core.telegram.org/bots/faq#my-bot-is-hitting-limits)) |\n| `TELEGRAM_PER_CHAT_RATE_LIMIT` | No | `20` | Max messages/min per group ([Telegram limit](https://core.telegram.org/bots/faq#my-bot-is-hitting-limits)) |\n| `TELEGRAM_MAX_RETRIES` | No | `3` | Retry attempts on transient errors |\n| `TELEGRAM_CB_THRESHOLD` | No | `5` | Failures before circuit opens |\n| `TELEGRAM_CB_COOLDOWN` | No | `30000` | Circuit breaker cooldown (ms) |\n| `TELEGRAM_ALLOWED_UPLOAD_DIRS` | No | — | Comma-separated allowed upload paths |\n| `TELEGRAM_MAX_FILE_SIZE` | No | `52428800` | Max upload file size (50MB) |\n\n## Meta Mode\n\nWhen `TELEGRAM_META_MODE=true`, the server exposes only 2 tools instead of 185:\n\n- **`telegram_find`** — search methods by keyword or category\n- **`telegram_call`** — call any method by name with JSON params\n\nThis saves ~99% of context tokens while keeping full API access:\n\n```\nUser: \"Post a poll in my channel\"\nAI: → telegram_find(query: \"poll\")\nAI: → telegram_call(method: \"sendPoll\", params: { chat_id: ..., question: \"...\", options: [...] })\n```\n\n## API Coverage\n\n185/185 methods — **100% Bot API 10.2** (July 2026)\n\n| Category | Count | Key methods |\n|----------|:---:|-------------|\n| Bot | 21 | getMe, setMyCommands, setMyProfilePhoto, getFile, getUserProfilePhotos |\n| Chat | 18 | getChat, setChatTitle, pinChatMessage, answerChatJoinRequestQuery, getUserPersonalChatMessages |\n| Stickers | 16 | sendSticker, createNewStickerSet, uploadStickerFile, setStickerKeywords |\n| Editing | 15 | editMessageText, editMessageMedia, deleteMessage, editEphemeralMessageText, deleteEphemeralMessage |\n| Business | 14 | readBusinessMessage, setBusinessAccountName, getBusinessAccountGifts, approveSuggestedPost |\n| Messages | 13 | sendMessage, sendRichMessage, sendRichMessageDraft, sendChecklist, deleteMessageReaction |\n| Forum | 13 | createForumTopic, editForumTopic, closeForumTopic, deleteForumTopic |\n| Media | 10 | sendPhoto, sendVideo, sendLivePhoto, sendMediaGroup, sendPaidMedia |\n| Members | 9 | banChatMember, promoteChatMember, setChatMemberTag, restrictChatMember |\n| Invite | 8 | createChatInviteLink, createChatSubscriptionInviteLink, approveChatJoinRequest |\n| Payments | 8 | sendInvoice, createInvoiceLink, getStarTransactions, getMyStarBalance |\n| Gifts | 8 | sendGift, getUserGifts, getChatGifts, giftPremiumSubscription, upgradeGift |\n| Inline | 5 | answerInlineQuery, answerCallbackQuery, answerGuestQuery, answerWebAppQuery |\n| Managed Bots | 5 | getManagedBotToken, getManagedBotAccessSettings, setManagedBotAccessSettings |\n| Other | 5 | verifyUser, verifyChat, setUserEmojiStatus, savePreparedInlineMessage |\n| Forwarding | 4 | forwardMessage, forwardMessages, copyMessage, copyMessages |\n| Stories | 4 | postStory, editStory, deleteStory, repostStory |\n| Updates | 4 | getUpdates, setWebhook, deleteWebhook, getWebhookInfo |\n| Games | 3 | sendGame, setGameScore, getGameHighScores |\n| Polls | 1 | sendPoll (revoting, shuffle, media, country restrictions) |\n| Passport | 1 | setPassportDataErrors |\n\n## Long posts: rich messages\n\n`send_photo` and friends cap the caption at **1024 characters** — that limit is set by Telegram and still applies. To publish a real post, use `send_rich_message` instead:\n\n```json\n{\n \"chat_id\": \"@mychannel\",\n \"rich_message\": {\n \"markdown\": \"# Heading\n\nParagraph with **bold** and a [link](https://t.me).\n\n![](https://example.com/cover.jpg \\\"Cover caption\\\")\n\n| Model | Speed |\n|:------|------:|\n| A | **42** |\n\n> Block quote\n\n- List item\n- Another item\"\n }\n}\n```\n\nNot sure of the syntax? Ask the server — it ships the reference:\n\n```\ntelegram_format(topic: \"rich_message\")\n```\n\n`telegram_format` also answers for `caption`, `media`, `reply_markup`, `poll`, `checklist`, `reply_parameters`, `link_preview_options` and `suggested_post_parameters`, by topic, by tool name (`send_media_group`), or in plain wording (`\"long post\"`, `\"album\"`, `\"buttons\"`). The same docs are served as MCP resources at `telegram://format/`.\n\nPass exactly one of `markdown` (GitHub-flavored, plus Telegram tags), `html`, or `blocks`. Limits enforced before the request leaves the server:\n\n| Limit | Value |\n|-------|:---:|\n| Text | 32768 characters |\n| Blocks (nested included) | 500 |\n| Media attachments | 50 |\n| Table columns | 20 |\n| Nesting levels | 16 |\n\nMedia inside `markdown`/`html` must be HTTP(S) URLs and sit in their own block. `send_rich_message_draft` streams a partial message as a 30-second preview while it is still being generated — finish with `send_rich_message` to persist it.\n\n## Architecture\n\n```\nsrc/\n├── index.ts # Entry point\n├── config.ts # Environment config with validation\n├── server.ts # MCP server (standard + meta mode)\n├── telegram-client.ts # HTTP client with retry, rate limit, circuit breaker\n├── rate-limiter.ts # Token bucket: global + per-chat\n├── circuit-breaker.ts # 3-state circuit breaker (closed/open/half-open)\n├── method-registry.ts # Declarative method definitions + Zod schema builder\n├── formats.ts # Reference for structured params, served by telegram_format\n└── methods/\n ├── index.ts # Aggregator + search\n ├── messages.ts # sendMessage, sendDice, sendChecklist, ...\n ├── forwarding.ts # forwardMessage, copyMessage, ...\n ├── editing.ts # editMessageText, deleteMessage, ...\n ├── chat.ts # getChat, setChatTitle, banChatMember, ...\n ├── bot.ts # getMe, setMyCommands, getFile, ...\n ├── forum.ts # createForumTopic, editForumTopic, ...\n ├── stickers.ts # sendSticker, createNewStickerSet, ...\n ├── payments.ts # sendInvoice, getStarTransactions, ...\n ├── business.ts # readBusinessMessage, setBusinessAccount*, ...\n ├── stories.ts # postStory, editStory, deleteStory, ...\n ├── gifts.ts # sendGift, getUserGifts, convertGiftToStars, ...\n ├── games.ts # sendGame, setGameScore, ...\n ├── inline.ts # answerInlineQuery, answerCallbackQuery\n ├── managed-bots.ts # getManagedBotToken, replaceManagedBotToken\n ├── updates.ts # getUpdates, setWebhook, ...\n ├── passport.ts # setPassportDataErrors\n └── other.ts # verifyUser, setChatMenuButton, ...\n\nscripts/\n├── refresh-docs.mjs # Re-download core.telegram.org/bots/* into docs/\n└── audit-registry.mjs # Diff src/methods against the docs mirror\n```\n\n### Design principles\n\n- **Declarative registry** — each method is pure data (name, params, types, annotations). One generic handler serves all 185 methods. Adding a new method = one array entry.\n- **Spec-checked** — `docs/` mirrors the official Bot API pages and `scripts/audit-registry.mjs` diffs the registry against it, so a new Telegram release surfaces as a failing check rather than a runtime 400.\n- **Zod validation** — every parameter validated before reaching Telegram. Clear error messages with hints instead of opaque API 400s.\n- **Token bucket rate limiting** — no race conditions (async mutex). Defaults match [Telegram's official limits](https://core.telegram.org/bots/faq#my-bot-is-hitting-limits): 30 req/sec global, 20 msg/min per group.\n- **Circuit breaker** — 429 (rate limit) is NOT counted as failure. Only real errors (5xx, network) trip the breaker. Half-open probe recovers automatically.\n- **Tool annotations** — every method has MCP annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) so AI clients know which tools are safe to auto-approve.\n- **Response truncation** — responses capped at 100K chars to prevent context window overflow.\n\n## Security\n\n- Bot token never appears in MCP tool responses or error messages (masked as `***`)\n- File upload paths validated against allowed directories (`TELEGRAM_ALLOWED_UPLOAD_DIRS`)\n- Path traversal attacks blocked (resolve + normalize + separator check)\n- No `eval()`, no `Function()`, no dynamic imports\n- No external requests except `api.telegram.org`\n- No telemetry, no analytics, no phone-home\n- Zero bloat: only 2 runtime dependencies (`@modelcontextprotocol/sdk` + `zod`)\n\n## Development\n\n```bash\nnpm install\nnpm run build # TypeScript compilation\nnpm run typecheck # Type checking without emit\nnpm test # Run all tests (vitest)\nnpm run test:watch # Watch mode\nnpm run lint # ESLint\nnpm run docs:refresh # Re-download the official Bot API docs into docs/\nnpm run audit # Diff the registry against the docs mirror\n```\n\n## Other Projects by [@timoncool](https://github.com/timoncool)\n\n| Project | Description |\n|---------|-------------|\n| [civitai-mcp-ultimate](https://github.com/timoncool/civitai-mcp-ultimate) | Civitai API as MCP server |\n| [trail-spec](https://github.com/timoncool/trail-spec) | TRAIL — cross-MCP content tracking protocol |\n| [ACE-Step Studio](https://github.com/timoncool/ACE-Step-Studio) | AI music studio — songs, vocals, covers, videos |\n| [VideoSOS](https://github.com/timoncool/videosos) | AI video production in the browser |\n| [tg-challenge-bot](https://github.com/timoncool/tg-challenge-bot) | AI anti-spam bot for Telegram |\n| [Bulka](https://github.com/timoncool/Bulka) | Live-coding music platform |\n\n## Support the Author\n\nI build open-source software and do AI research. Most of what I create is free and available to everyone. Your donations help me keep creating without worrying about where the next meal comes from =)\n\n**[All donation methods](https://github.com/timoncool/ACE-Step-Studio/blob/master/DONATE.md)** | **[dalink.to/nerual_dreming](https://dalink.to/nerual_dreming)** | **[boosty.to/neuro_art](https://boosty.to/neuro_art)**\n\n- **BTC:** `1E7dHL22RpyhJGVpcvKdbyZgksSYkYeEBC`\n- **ETH (ERC20):** `0xb5db65adf478983186d4897ba92fe2c25c594a0c`\n- **USDT (TRC20):** `TQST9Lp2TjK6FiVkn4fwfGUee7NmkxEE7C`\n\n\n## Star History\n\n\n \n \n \n \n \n\n\n## License\n\nMIT\n"}
![\"Star](\"docs/stars-dark.svg\")
\n