Production-ready MCP Server for Telegram Bot API - 162 methods with token-optimized meta mode
npm install @tonresistor/telegram-mcp
Production-ready MCP server for the complete Telegram Bot API. 162 methods with token-optimized meta mode (~157 tokens vs ~55,000).
- Complete API coverage — All 162 Telegram Bot API methods
- Token efficient — Meta mode reduces context by 99.7%
- Production hardened — Circuit breaker, rate limiting, retries with backoff
- Observable — Prometheus metrics, structured logging, health checks
- Type safe — Full TypeScript with Zod validation
``bash`
npm install && npm run build
Get your bot token from @BotFather, then add to your MCP config:
`json`
{
"mcpServers": {
"telegram": {
"command": "node",
"args": ["/path/to/build/index-meta.js"],
"env": {
"TELEGRAM_BOT_TOKEN": "your_token_here"
}
}
}
}
| Mode | Entry Point | Tools | Best For |
|------|-------------|-------|----------|
| Meta (recommended) | index-meta.js | 2 | Production — minimal token usage |index.js
| Standard | | 161 | Development — direct tool access |
Meta mode exposes just 2 tools:
- telegram_find — Search methods by name or categorytelegram_call
- — Execute any Telegram API method
| Variable | Default | Description |
|----------|---------|-------------|
| TELEGRAM_BOT_TOKEN | required | Bot token from BotFather |LOG_LEVEL
| | info | debug / info / warning / error / critical |REQUEST_TIMEOUT
| | 30000 | Request timeout in ms (5000-120000) |MAX_RETRIES
| | 3 | Retry attempts (0-10) |RATE_LIMIT_PER_MINUTE
| | 30 | Global rate limit (1-60) |HEALTH_PORT
| | — | Enable health endpoints (/health, /metrics) |
All 161 Telegram Bot API methods organized by category.
Messages (23 methods)
| Method | Description |
|--------|-------------|
| sendMessage | Send text message |sendPhoto
| | Send photo |sendVideo
| | Send video |sendAudio
| | Send audio file |sendDocument
| | Send document/file |sendAnimation
| | Send GIF animation |sendVoice
| | Send voice message |sendVideoNote
| | Send video note (round video) |sendLocation
| | Send location |sendVenue
| | Send venue/place |sendContact
| | Send phone contact |sendPoll
| | Send poll/survey |sendDice
| | Send animated dice |sendChatAction
| | Send typing indicator |sendMediaGroup
| | Send media album |sendPaidMedia
| | Send paid media |sendMessageDraft
| | Stream partial message (AI) |forwardMessage
| | Forward message |forwardMessages
| | Forward multiple messages |copyMessage
| | Copy message |copyMessages
| | Copy multiple messages |sendSticker
| | Send sticker |sendChecklist
| | Send checklist (business) |
Chat Management (30 methods)
| Method | Description |
|--------|-------------|
| getChat | Get chat info |getChatMember
| | Get member info |getChatMemberCount
| | Get member count |getChatAdministrators
| | List administrators |banChatMember
| | Ban user |unbanChatMember
| | Unban user |restrictChatMember
| | Restrict user |promoteChatMember
| | Promote to admin |setChatAdministratorCustomTitle
| | Set admin title |setChatPermissions
| | Set default permissions |setChatTitle
| | Set chat title |setChatDescription
| | Set chat description |setChatPhoto
| | Set chat photo |deleteChatPhoto
| | Delete chat photo |pinChatMessage
| | Pin message |unpinChatMessage
| | Unpin message |unpinAllChatMessages
| | Unpin all messages |leaveChat
| | Leave chat |exportChatInviteLink
| | Generate invite link |createChatInviteLink
| | Create invite link |editChatInviteLink
| | Edit invite link |revokeChatInviteLink
| | Revoke invite link |approveChatJoinRequest
| | Approve join request |declineChatJoinRequest
| | Decline join request |banChatSenderChat
| | Ban channel |unbanChatSenderChat
| | Unban channel |setChatStickerSet
| | Set sticker set |deleteChatStickerSet
| | Delete sticker set |createChatSubscriptionInviteLink
| | Create subscription link |editChatSubscriptionInviteLink
| | Edit subscription link |
Editing (9 methods)
| Method | Description |
|--------|-------------|
| editMessageText | Edit text |editMessageCaption
| | Edit caption |editMessageMedia
| | Edit media |editMessageReplyMarkup
| | Edit keyboard |editMessageLiveLocation
| | Edit live location |stopMessageLiveLocation
| | Stop live location |stopPoll
| | Stop poll |deleteMessage
| | Delete message |deleteMessages
| | Delete multiple messages |
Settings (16 methods)
| Method | Description |
|--------|-------------|
| setMyCommands | Set commands |getMyCommands
| | Get commands |deleteMyCommands
| | Delete commands |setMyName
| | Set bot name |getMyName
| | Get bot name |setMyDescription
| | Set description |getMyDescription
| | Get description |setMyShortDescription
| | Set short description |getMyShortDescription
| | Get short description |setChatMenuButton
| | Set menu button |getChatMenuButton
| | Get menu button |setMyDefaultAdministratorRights
| | Set default admin rights |getMyDefaultAdministratorRights
| | Get default admin rights |getUserProfilePhotos
| | Get user photos |getFile
| | Get file info |setUserEmojiStatus
| | Set emoji status |
Business (16 methods)
| Method | Description |
|--------|-------------|
| getBusinessConnection | Get connection info |readBusinessMessage
| | Mark as read |deleteBusinessMessages
| | Delete messages |setBusinessAccountName
| | Set account name |setBusinessAccountUsername
| | Set username |setBusinessAccountBio
| | Set bio |setBusinessAccountProfilePhoto
| | Set profile photo |removeBusinessAccountProfilePhoto
| | Remove photo |setBusinessAccountGiftSettings
| | Set gift settings |getBusinessAccountStarBalance
| | Get star balance |transferBusinessAccountStars
| | Transfer stars |postStory
| | Post story |editStory
| | Edit story |deleteStory
| | Delete story |repostStory
| | Repost story |approveSuggestedPost
| | Approve post |declineSuggestedPost
| | Decline post |
Stickers (16 methods)
| Method | Description |
|--------|-------------|
| getStickerSet | Get sticker set |getCustomEmojiStickers
| | Get custom emojis |uploadStickerFile
| | Upload sticker |createNewStickerSet
| | Create set |addStickerToSet
| | Add to set |setStickerPositionInSet
| | Move position |deleteStickerFromSet
| | Delete from set |replaceStickerInSet
| | Replace sticker |setStickerEmojiList
| | Set emojis |setStickerKeywords
| | Set keywords |setStickerMaskPosition
| | Set mask position |setStickerSetTitle
| | Set title |setStickerSetThumbnail
| | Set thumbnail |setCustomEmojiStickerSetThumbnail
| | Set emoji thumbnail |deleteStickerSet
| | Delete set |
Forum Topics (13 methods)
| Method | Description |
|--------|-------------|
| getForumTopicIconStickers | Get icon stickers |createForumTopic
| | Create topic |editForumTopic
| | Edit topic |closeForumTopic
| | Close topic |reopenForumTopic
| | Reopen topic |deleteForumTopic
| | Delete topic |unpinAllForumTopicMessages
| | Unpin all |editGeneralForumTopic
| | Edit General |closeGeneralForumTopic
| | Close General |reopenGeneralForumTopic
| | Reopen General |hideGeneralForumTopic
| | Hide General |unhideGeneralForumTopic
| | Unhide General |unpinAllGeneralForumTopicMessages
| | Unpin General |
Inline & Callbacks (6 methods)
| Method | Description |
|--------|-------------|
| answerInlineQuery | Answer inline query |answerCallbackQuery
| | Answer callback |answerWebAppQuery
| | Answer Web App |savePreparedInlineMessage
| | Save prepared message |setMessageReaction
| | Set reaction |getUserChatBoosts
| | Get user boosts |
Payments (8 methods)
| Method | Description |
|--------|-------------|
| sendInvoice | Send invoice |createInvoiceLink
| | Create invoice link |answerShippingQuery
| | Answer shipping |answerPreCheckoutQuery
| | Answer pre-checkout |getStarTransactions
| | Get transactions |refundStarPayment
| | Refund payment |editUserStarSubscription
| | Edit subscription |getMyStarBalance
| | Get balance |
Gifts (9 methods)
| Method | Description |
|--------|-------------|
| getAvailableGifts | Get available gifts |sendGift
| | Send gift |giftPremiumSubscription
| | Gift Premium |getUserGifts
| | Get user gifts |getChatGifts
| | Get chat gifts |getBusinessAccountGifts
| | Get business gifts |convertGiftToStars
| | Convert to stars |upgradeGift
| | Upgrade gift |transferGift
| | Transfer gift |
Games (3 methods)
| Method | Description |
|--------|-------------|
| sendGame | Send game |setGameScore
| | Set score |getGameHighScores
| | Get high scores |
Updates & Bot (7 methods)
| Method | Description |
|--------|-------------|
| getUpdates | Get updates (polling) |setWebhook
| | Set webhook |deleteWebhook
| | Delete webhook |getWebhookInfo
| | Get webhook info |getMe
| | Get bot info |logOut
| | Log out |close
| | Close instance |
Verification & Passport (5 methods)
| Method | Description |
|--------|-------------|
| verifyUser | Verify user |verifyChat
| | Verify chat |removeUserVerification
| | Remove user verification |removeChatVerification
| | Remove chat verification |setPassportDataErrors
| | Set Passport errors |
`bash``
npm test # Run tests
npm run build # Compile TypeScript
MIT