telegram-api-mcp

Ultimate MCP server for Telegram Bot API — 169 methods, full v9.6 coverage, meta-mode, rate limiting, circuit breaker.

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

Features

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

• Bot API 9.6 (April 2026) — managed bots, revoting polls, shuffle options, poll descriptions

• Meta-mode — 2 tools instead of 169, 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 169 methods annotated (readOnly, destructive, idempotent, openWorld)

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

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

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 169:

• 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

169/169 methods — 100% Bot API 9.6 (April 2026)

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
└── 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, ...

Design principles

• Declarative registry — each method is pure data (name, params, types, annotations). One generic handler serves all 169 methods. Adding a new method = one array entry.

• 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

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