telegram-api-mcp

Ultimate MCP server for Telegram Bot API — 185 methods, full v10.2 coverage, rich messages, meta-mode, rate limiting, circuit breaker.

185/185 Bot API methods with Zod validation, token masking, tool annotations, and zero bloat (2 dependencies).

Features

• 185/185 Bot API methods — messages, media, polls, chats, forums, stickers, payments, business, stories, gifts, games, inline, managed bots

• 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

• Bot API 10.2 (July 2026) — rich messages, ephemeral messages, live photos, guest mode, join-request queries, poll media

• 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/…)

• Meta-mode — 2 tools instead of 185, saves ~99% context tokens

• Rate limiting — global (30 req/sec) + per-chat (20 msg/min), token bucket with async mutex

• Circuit breaker — 3-state (closed/open/half-open), auto-recovery

• Retry with backoff — respects Telegram 429 retry_after, exponential backoff on 5xx

• Zod validation — every parameter validated before hitting Telegram API

• Token masking — bot token never appears in responses, logs, or error messages

• File upload security — path traversal protection, configurable allowed directories

• Tool annotations — all 185 methods annotated (readOnly, destructive, idempotent, openWorld)

• Docs mirror + audit — npm run docs:refresh re-downloads the official spec, npm run audit fails if any method or parameter drifts from it

• Response truncation — 100K char limit to prevent context overflow

• Zero bloat — only 2 dependencies: @modelcontextprotocol/sdk + zod

Related MCP server: telegram-bot-mcp

Quick Start

Claude Code

claude mcp add telegram -- npx telegram-api-mcp -e TELEGRAM_BOT_TOKEN=your_token

With meta-mode (recommended for large conversations):

claude mcp add telegram -- npx telegram-api-mcp \
  -e TELEGRAM_BOT_TOKEN=your_token \
  -e TELEGRAM_META_MODE=true

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": ["telegram-api-mcp"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your_token_from_botfather"
      }
    }
  }
}

With default chat (skip chat_id in every call)

{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": ["telegram-api-mcp"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your_token",
        "TELEGRAM_DEFAULT_CHAT_ID": "-1001234567890"
      }
    }
  }
}

From source

git clone https://github.com/timoncool/telegram-api-mcp.git
cd telegram-api-mcp
npm install && npm run build
TELEGRAM_BOT_TOKEN=your_token node dist/index.js

Environment Variables

Meta Mode

When TELEGRAM_META_MODE=true, the server exposes only 2 tools instead of 185:

• telegram_find — search methods by keyword or category

• telegram_call — call any method by name with JSON params

This saves ~99% of context tokens while keeping full API access:

User: "Post a poll in my channel"
AI: → telegram_find(query: "poll")
AI: → telegram_call(method: "sendPoll", params: { chat_id: ..., question: "...", options: [...] })

API Coverage

185/185 methods — 100% Bot API 10.2 (July 2026)

Long posts: rich messages

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:

{
  "chat_id": "@mychannel",
  "rich_message": {
    "markdown": "# Heading

Paragraph with **bold** and a [link](https://t.me).

![](https://example.com/cover.jpg \"Cover caption\")

| Model | Speed |
|:------|------:|
| A | **42** |

> Block quote

- List item
- Another item"
  }
}

Not sure of the syntax? Ask the server — it ships the reference:

telegram_format(topic: "rich_message")

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/<topic>.

Pass exactly one of markdown (GitHub-flavored, plus Telegram tags), html, or blocks. Limits enforced before the request leaves the server:

Media 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.

Architecture

src/
├── index.ts              # Entry point
├── config.ts             # Environment config with validation
├── server.ts             # MCP server (standard + meta mode)
├── telegram-client.ts    # HTTP client with retry, rate limit, circuit breaker
├── rate-limiter.ts       # Token bucket: global + per-chat
├── circuit-breaker.ts    # 3-state circuit breaker (closed/open/half-open)
├── method-registry.ts    # Declarative method definitions + Zod schema builder
├── formats.ts            # Reference for structured params, served by telegram_format
└── methods/
    ├── index.ts          # Aggregator + search
    ├── messages.ts       # sendMessage, sendDice, sendChecklist, ...
    ├── forwarding.ts     # forwardMessage, copyMessage, ...
    ├── editing.ts        # editMessageText, deleteMessage, ...
    ├── chat.ts           # getChat, setChatTitle, banChatMember, ...
    ├── bot.ts            # getMe, setMyCommands, getFile, ...
    ├── forum.ts          # createForumTopic, editForumTopic, ...
    ├── stickers.ts       # sendSticker, createNewStickerSet, ...
    ├── payments.ts       # sendInvoice, getStarTransactions, ...
    ├── business.ts       # readBusinessMessage, setBusinessAccount*, ...
    ├── stories.ts        # postStory, editStory, deleteStory, ...
    ├── gifts.ts          # sendGift, getUserGifts, convertGiftToStars, ...
    ├── games.ts          # sendGame, setGameScore, ...
    ├── inline.ts         # answerInlineQuery, answerCallbackQuery
    ├── managed-bots.ts   # getManagedBotToken, replaceManagedBotToken
    ├── updates.ts        # getUpdates, setWebhook, ...
    ├── passport.ts       # setPassportDataErrors
    └── other.ts          # verifyUser, setChatMenuButton, ...

scripts/
├── refresh-docs.mjs      # Re-download core.telegram.org/bots/* into docs/
└── audit-registry.mjs    # Diff src/methods against the docs mirror

Design principles

• 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.

• 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.

• Zod validation — every parameter validated before reaching Telegram. Clear error messages with hints instead of opaque API 400s.

• Token bucket rate limiting — no race conditions (async mutex). Defaults match Telegram's official limits: 30 req/sec global, 20 msg/min per group.

• Circuit breaker — 429 (rate limit) is NOT counted as failure. Only real errors (5xx, network) trip the breaker. Half-open probe recovers automatically.

• Tool annotations — every method has MCP annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) so AI clients know which tools are safe to auto-approve.

• Response truncation — responses capped at 100K chars to prevent context window overflow.

Security

• Bot token never appears in MCP tool responses or error messages (masked as ***)

• File upload paths validated against allowed directories (TELEGRAM_ALLOWED_UPLOAD_DIRS)

• Path traversal attacks blocked (resolve + normalize + separator check)

• No eval(), no Function(), no dynamic imports

• No external requests except api.telegram.org

• No telemetry, no analytics, no phone-home

• Zero bloat: only 2 runtime dependencies (@modelcontextprotocol/sdk + zod)

Development

npm install
npm run build         # TypeScript compilation
npm run typecheck     # Type checking without emit
npm test              # Run all tests (vitest)
npm run test:watch    # Watch mode
npm run lint          # ESLint
npm run docs:refresh  # Re-download the official Bot API docs into docs/
npm run audit         # Diff the registry against the docs mirror

Other Projects by @timoncool

Support the Author

I 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 =)

All donation methods | dalink.to/nerual_dreming | boosty.to/neuro_art

• BTC: 1E7dHL22RpyhJGVpcvKdbyZgksSYkYeEBC

• ETH (ERC20): 0xb5db65adf478983186d4897ba92fe2c25c594a0c

• USDT (TRC20): TQST9Lp2TjK6FiVkn4fwfGUee7NmkxEE7C

Star History

License

MIT