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

Variable	Required	Default	Description
TELEGRAM_BOT_TOKEN	Yes	—	Bot token from @BotFather
TELEGRAM_DEFAULT_CHAT_ID	No	—	Default chat ID for all tools
TELEGRAM_DEFAULT_THREAD_ID	No	—	Default forum topic thread ID
TELEGRAM_META_MODE	No	false	Use 2 meta-tools instead of 169
TELEGRAM_GLOBAL_RATE_LIMIT	No	30	Max requests/sec (Telegram limit)
TELEGRAM_PER_CHAT_RATE_LIMIT	No	20	Max messages/min per group (Telegram limit)
TELEGRAM_MAX_RETRIES	No	3	Retry attempts on transient errors
TELEGRAM_CB_THRESHOLD	No	5	Failures before circuit opens
TELEGRAM_CB_COOLDOWN	No	30000	Circuit breaker cooldown (ms)
TELEGRAM_ALLOWED_UPLOAD_DIRS	No	—	Comma-separated allowed upload paths
TELEGRAM_MAX_FILE_SIZE	No	52428800	Max upload file size (50MB)

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)

Category	Count	Key methods
Bot	21	getMe, setMyCommands, setMyProfilePhoto, getFile, getUserProfilePhotos
Stickers	16	sendSticker, createNewStickerSet, uploadStickerFile, setStickerKeywords
Chat	15	getChat, setChatTitle, setChatPermissions, pinChatMessage, leaveChat
Business	14	readBusinessMessage, setBusinessAccountName, getBusinessConnection
Forum	13	createForumTopic, editForumTopic, closeForumTopic, deleteForumTopic
Editing	10	editMessageText, editMessageMedia, deleteMessage, deleteMessages, stopPoll
Messages	9	sendMessage, sendMessageDraft, sendLocation, sendContact, sendChecklist
Media	9	sendPhoto, sendVideo, sendAudio, sendDocument, sendMediaGroup, sendPaidMedia
Members	9	banChatMember, promoteChatMember, setChatMemberTag, restrictChatMember
Invite	8	createChatInviteLink, createChatSubscriptionInviteLink, approveChatJoinRequest
Payments	8	sendInvoice, createInvoiceLink, getStarTransactions, getMyStarBalance
Gifts	8	sendGift, getUserGifts, getChatGifts, giftPremiumSubscription, upgradeGift
Other	5	verifyUser, verifyChat, setUserEmojiStatus, savePreparedInlineMessage
Forwarding	4	forwardMessage, forwardMessages, copyMessage, copyMessages
Stories	4	postStory, editStory, deleteStory, repostStory
Inline	4	answerInlineQuery, answerCallbackQuery, answerWebAppQuery, savePreparedInlineMessage
Updates	4	getUpdates, setWebhook, deleteWebhook, getWebhookInfo
Games	3	sendGame, setGameScore, getGameHighScores
Managed Bots	3	getManagedBotToken, replaceManagedBotToken, savePreparedKeyboardButton
Polls	1	sendPoll (v9.6: revoting, shuffle, multiple correct, descriptions)
Passport	1	setPassportDataErrors

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

Project	Description
civitai-mcp-ultimate	Civitai API as MCP server
trail-spec	TRAIL — cross-MCP content tracking protocol
ACE-Step Studio	AI music studio — songs, vocals, covers, videos
VideoSOS	AI video production in the browser
tg-challenge-bot	AI anti-spam bot for Telegram
Bulka	Live-coding music platform

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