Skip to main content
Glama
telegram-api-mcp

telegram-api-mcp

by timoncool

telegram-api-mcp

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

Stars npm License Bot API TRAIL

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

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 185

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

Category

Count

Key methods

Bot

21

getMe, setMyCommands, setMyProfilePhoto, getFile, getUserProfilePhotos

Chat

18

getChat, setChatTitle, pinChatMessage, answerChatJoinRequestQuery, getUserPersonalChatMessages

Stickers

16

sendSticker, createNewStickerSet, uploadStickerFile, setStickerKeywords

Editing

15

editMessageText, editMessageMedia, deleteMessage, editEphemeralMessageText, deleteEphemeralMessage

Business

14

readBusinessMessage, setBusinessAccountName, getBusinessAccountGifts, approveSuggestedPost

Messages

13

sendMessage, sendRichMessage, sendRichMessageDraft, sendChecklist, deleteMessageReaction

Forum

13

createForumTopic, editForumTopic, closeForumTopic, deleteForumTopic

Media

10

sendPhoto, sendVideo, sendLivePhoto, 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

Inline

5

answerInlineQuery, answerCallbackQuery, answerGuestQuery, answerWebAppQuery

Managed Bots

5

getManagedBotToken, getManagedBotAccessSettings, setManagedBotAccessSettings

Other

5

verifyUser, verifyChat, setUserEmojiStatus, savePreparedInlineMessage

Forwarding

4

forwardMessage, forwardMessages, copyMessage, copyMessages

Stories

4

postStory, editStory, deleteStory, repostStory

Updates

4

getUpdates, setWebhook, deleteWebhook, getWebhookInfo

Games

3

sendGame, setGameScore, getGameHighScores

Polls

1

sendPoll (revoting, shuffle, media, country restrictions)

Passport

1

setPassportDataErrors

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:

Limit

Value

Text

32768 characters

Blocks (nested included)

500

Media attachments

50

Table columns

20

Nesting levels

16

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

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

Available Tools

173 tools
add_sticker_to_setC
Idempotent

Add a sticker to an existing set.

Inputs: name (required), user_id (required), sticker.

answer_callback_queryB

Answer a callback query from an inline keyboard button.

Inputs: callback_query_id (required), url, text, cache_time, +1 more.

answer_inline_queryB

Send answers to an inline query. Max 50 results per query.

Inputs: inline_query_id (required), button, results, cache_time, +2 more.

answer_pre_checkout_queryA

Respond to pre-checkout queries. Must answer within 10 seconds.

Inputs: ok (required), pre_checkout_query_id (required), error_message.

answer_shipping_queryC

Reply to shipping queries. Called if sendInvoice used is_flexible.

Inputs: ok (required), shipping_query_id (required), error_message, shipping_options.

answer_web_app_queryA

Set the result of an interaction with a Web App and send a message on behalf of the user.

Inputs: web_app_query_id (required), result.

approve_chat_join_requestA
Idempotent

Approve a chat join request.

Inputs: chat_id (required), user_id (required).

approve_suggested_postC
Idempotent

Approve a suggested post for a channel (v9.2).

Inputs: message_id (required), business_connection_id (required).

ban_chat_memberA
Destructive

Ban a user from a chat. In supergroups/channels, the user cannot return without being unbanned.

Inputs: chat_id (required), user_id (required), until_date, revoke_messages.

ban_chat_sender_chatA
Destructive

Ban a channel chat from sending messages in a supergroup.

Inputs: chat_id (required), sender_chat_id (required).

closeA
Idempotent

Close the bot instance. Use before moving between local servers.

Inputs: no named parameters.

close_forum_topicA
Idempotent

Close an open topic in a forum supergroup.

Inputs: chat_id (required), message_thread_id (required).

close_general_forum_topicC
Idempotent

Close the 'General' topic.

Inputs: chat_id (required).

convert_gift_to_starsC
Idempotent

Convert a gift to Telegram Stars (v9.0).

Inputs: owned_gift_id (required), business_connection_id (required).

copy_messageA

Copy a message (sends without 'Forwarded from' header). Can change caption.

Inputs: chat_id (required), message_id (required), from_chat_id (required), caption, +8 more.

copy_messagesC

Copy multiple messages at once.

Inputs: chat_id (required), message_ids (required), from_chat_id (required), remove_caption, +3 more.

create_forum_topicA

Create a topic in a forum supergroup or private chat (v9.4+).

Inputs: name (required), chat_id (required), icon_color, icon_custom_emoji_id.

create_new_sticker_setC

Create a new sticker set owned by a user.

Inputs: name (required), title (required), user_id (required), stickers, +2 more.

decline_chat_join_requestB
Idempotent

Decline a chat join request.

Inputs: chat_id (required), user_id (required).

decline_suggested_postC
Idempotent

Decline a suggested post for a channel (v9.2).

Inputs: message_id (required), business_connection_id (required).

delete_business_messagesB
Destructive

Delete business messages.

Inputs: message_ids (required), business_connection_id (required).

delete_chat_photoA
Destructive

Delete a chat photo.

Inputs: chat_id (required).

delete_chat_sticker_setA
Destructive

Delete the sticker set from a supergroup.

Inputs: chat_id (required).

delete_forum_topicA
Destructive

Delete a forum topic along with all its messages.

Inputs: chat_id (required), message_thread_id (required).

delete_messageA
Destructive

Delete a message. Bot must have delete rights in the chat.

Inputs: chat_id (required), message_id (required).

delete_messagesA
Destructive

Delete multiple messages at once. Max 100 messages.

Inputs: chat_id (required), message_ids (required).

delete_my_commandsB
Destructive

Delete the bot's command list for a given scope and language.

Inputs: scope, language_code.

delete_sticker_from_setC
Destructive

Delete a sticker from a set.

Inputs: sticker (required).

delete_sticker_setA
Destructive

Delete a sticker set created by the bot.

Inputs: name (required).

delete_storyC
Destructive

Delete a story (v9.0).

Inputs: story_id (required), business_connection_id (required).

delete_webhookA
Destructive

Remove webhook integration and switch back to getUpdates.

Inputs: drop_pending_updates.

download_fileA
Idempotent

Download a file from Telegram by file_id. Saves locally and returns the path. Use after receiving a message with a photo, video, document, voice, etc. Max 20MB (Telegram Bot API limit).

Inputs: file_id (required), dest_dir.

edit_forum_topicA
Idempotent

Edit name and icon of a forum topic.

Inputs: chat_id (required), message_thread_id (required), name, icon_custom_emoji_id.

edit_general_forum_topicA
Idempotent

Edit the name of the 'General' forum topic.

Inputs: name (required), chat_id (required).

edit_message_captionA
Idempotent

Edit the caption of a media message.

Inputs: caption, chat_id, message_id, parse_mode, +4 more.

edit_message_checklistC
Idempotent

Edit a checklist message (v9.1).

Inputs: chat_id (required), message_id (required), checklist, reply_markup.

edit_message_live_locationC
Idempotent

Edit a live location message.

Inputs: latitude (required), longitude (required), chat_id, heading, +5 more.

edit_message_mediaA
Idempotent

Edit the media content of a message (photo, video, animation, document, audio).

Inputs: media, chat_id, message_id, reply_markup, +1 more.

edit_message_reply_markupC
Idempotent

Edit the inline keyboard of a message.

Inputs: chat_id, message_id, reply_markup, inline_message_id.

edit_message_textA
Idempotent

Edit the text of a message sent by the bot or via inline mode.

Inputs: text (required), chat_id, entities, message_id, +4 more.

edit_storyC
Idempotent

Edit a posted story (v9.0).

Inputs: story_id (required), business_connection_id (required), areas, caption, +3 more.

edit_user_star_subscriptionC
Idempotent

Edit a user's Star subscription (cancel or extend).

Inputs: user_id (required), is_canceled (required), telegram_payment_charge_id (required).

forward_messageC

Forward a message from one chat to another.

Inputs: chat_id (required), message_id (required), from_chat_id (required), protect_content, +2 more.

forward_messagesA

Forward multiple messages at once (maintains album grouping).

Inputs: chat_id (required), message_ids (required), from_chat_id (required), protect_content, +2 more.

get_available_giftsA
Read-onlyIdempotent

Get the list of gifts that can be sent.

Inputs: no named parameters.

get_business_account_giftsB
Read-onlyIdempotent

Get gifts received by a business account.

Inputs: business_connection_id (required), exclude_from_blockchain.

get_business_account_star_balanceA
Read-onlyIdempotent

Get the Telegram Stars balance of a business account.

Inputs: business_connection_id (required).

get_business_connectionC
Read-onlyIdempotent

Get information about a business connection.

Inputs: business_connection_id (required).

get_chatA
Read-onlyIdempotent

Get full information about a chat (title, description, photo, member count, permissions, etc).

Inputs: chat_id (required).

get_chat_administratorsA
Read-onlyIdempotent

Get a list of administrators in a chat.

Inputs: chat_id (required).

get_chat_giftsA
Read-onlyIdempotent

Get gifts received by a chat (v9.3).

Inputs: chat_id (required).

get_chat_memberB
Read-onlyIdempotent

Get information about a member in a chat.

Inputs: chat_id (required), user_id (required).

get_chat_member_countA
Read-onlyIdempotent

Get the number of members in a chat.

Inputs: chat_id (required).

get_chat_menu_buttonA
Read-onlyIdempotent

Get the current menu button for a chat or default.

Inputs: chat_id.

get_custom_emoji_stickersA
Read-onlyIdempotent

Get information about custom emoji stickers by their identifiers.

Inputs: custom_emoji_ids (required).

get_fileA
Read-onlyIdempotent

Get file info for downloading. Returns file_path — use https://api.telegram.org/file/bot/<file_path> to download.

Inputs: file_id (required).

get_forum_topic_icon_stickersA
Read-onlyIdempotent

Get custom emoji stickers that can be used as forum topic icons.

Inputs: no named parameters.

get_game_high_scoresC
Read-onlyIdempotent

Get high scores for a game.

Inputs: user_id (required), chat_id, message_id, inline_message_id.

get_managed_bot_tokenA
Read-onlyIdempotent

Get the token of a managed bot (v9.6).

Inputs: user_id (required).

get_meA
Read-onlyIdempotent

Get basic information about the bot (id, name, username, etc).

Inputs: no named parameters.

get_my_commandsA
Read-onlyIdempotent

Get the bot's current command list.

Inputs: scope, language_code.

get_my_default_administrator_rightsB
Read-onlyIdempotent

Get default admin rights.

Inputs: for_channels.

get_my_descriptionB
Read-onlyIdempotent

Get the bot's description.

Inputs: language_code.

get_my_nameA
Read-onlyIdempotent

Get the bot's name for a given language.

Inputs: language_code.

get_my_short_descriptionB
Read-onlyIdempotent

Get the bot's short description.

Inputs: language_code.

get_my_star_balanceA
Read-onlyIdempotent

Get the bot's Telegram Stars balance (v9.1).

Inputs: no named parameters.

get_star_transactionsC
Read-onlyIdempotent

Get the bot's Telegram Star transactions.

Inputs: limit, offset.

get_sticker_setA
Read-onlyIdempotent

Get a sticker set by name.

Inputs: name (required).

get_trailA
Read-onlyIdempotent

Query the TRAIL content log. Check what content was posted, failed, or skipped across pipelines.

Inputs: limit, since, action, offset, +3 more.

get_trail_statsA
Read-onlyIdempotent

Get summary statistics from the TRAIL content log.

Inputs: since, requester.

get_updatesA
Read-onlyIdempotent

Receive incoming updates via long polling.

Inputs: limit, offset, timeout, allowed_updates.

get_user_chat_boostsA
Read-onlyIdempotent

Get a user's boosts in a chat.

Inputs: chat_id (required), user_id (required).

get_user_giftsB
Read-onlyIdempotent

Get gifts received by a user (v9.3).

Inputs: user_id (required).

get_user_profile_audiosB
Read-onlyIdempotent

Get a user's profile audio tracks (v9.4).

Inputs: user_id (required), limit, offset.

get_user_profile_photosC
Read-onlyIdempotent

Get a user's profile photos.

Inputs: user_id (required), limit, offset.

get_webhook_infoA
Read-onlyIdempotent

Get current webhook status.

Inputs: no named parameters.

gift_premium_subscriptionB

Gift a Telegram Premium subscription (v9.0).

Inputs: user_id (required), star_count (required), month_count (required).

hide_general_forum_topicB
Idempotent

Hide the 'General' topic.

Inputs: chat_id (required).

leave_chatA
Destructive

Bot leaves a group, supergroup, or channel.

Inputs: chat_id (required).

log_outA
Idempotent

Log out from the cloud Bot API server. Use before moving to a local server.

Inputs: no named parameters.

mark_trailA

Write an entry to the TRAIL content log. Use to explicitly record content actions.

Inputs: action (required), requester (required), content_id (required), tags, +2 more.

pin_chat_messageC
Idempotent

Pin a message in a chat.

Inputs: chat_id (required), message_id (required), disable_notification, business_connection_id.

post_storyC

Post a story on behalf of a business account (v9.0).

Inputs: active_period (required), business_connection_id (required), areas, caption, +5 more.

promote_chat_memberB
Idempotent

Promote or demote a user in a supergroup or channel.

Inputs: chat_id (required), user_id (required), is_anonymous, can_change_info, +15 more.

read_business_messageC
Idempotent

Mark a business message as read.

Inputs: chat_id (required), message_id (required), business_connection_id (required).

refund_star_paymentC
Idempotent

Refund a Telegram Star payment.

Inputs: user_id (required), telegram_payment_charge_id (required).

remove_business_account_profile_photoC
Idempotent

Remove a business account profile photo.

Inputs: business_connection_id (required), photo_id.

remove_chat_verificationB
Idempotent

Remove chat verification.

Inputs: chat_id (required).

remove_my_profile_photoC
Idempotent

Remove the bot's profile photo (v9.4).

Inputs: photo_id.

remove_user_verificationB
Idempotent

Remove user verification.

Inputs: user_id (required).

reopen_forum_topicB
Idempotent

Reopen a closed topic.

Inputs: chat_id (required), message_thread_id (required).

reopen_general_forum_topicA
Idempotent

Reopen the 'General' topic.

Inputs: chat_id (required).

replace_managed_bot_tokenA
Idempotent

Replace the token of a managed bot (v9.6).

Inputs: user_id (required).

replace_sticker_in_setB
Idempotent

Replace an existing sticker in a set with a new one.

Inputs: name (required), user_id (required), old_sticker (required), sticker.

repost_storyC

Repost a story to another chat (v9.3).

Inputs: chat_id (required), story_id (required), story_sender_chat_id (required).

restrict_chat_memberB
Idempotent

Restrict a user's permissions in a supergroup.

Inputs: chat_id (required), user_id (required), until_date, permissions, +1 more.

save_prepared_inline_messageB
Idempotent

Save a prepared inline message result for a user to send via inline button.

Inputs: user_id (required), result, allow_bot_chats, allow_user_chats, +2 more.

save_prepared_keyboard_buttonB
Idempotent

Save a prepared keyboard button for later use (v9.6).

Inputs: user_id (required), button.

send_animationA

Send an animation (GIF or H.264/MPEG-4 AVC video without sound).

Inputs: chat_id (required), animation (required), width, height, +14 more.

send_audioB

Send an audio file. Telegram clients display it in the music player.

Inputs: audio (required), chat_id (required), title, caption, +13 more.

send_chat_actionB

Tell the user that the bot is performing an action (typing, uploading, etc).

Inputs: action (required), chat_id (required), message_thread_id, business_connection_id.

send_checklistC

Send an interactive checklist (v9.1).

Inputs: chat_id (required), checklist, effect_id, reply_markup, +6 more.

send_contactC

Send a phone contact.

Inputs: chat_id (required), first_name (required), phone_number (required), vcard, +9 more.

send_diceC

Send an animated emoji that displays a random value.

Inputs: chat_id (required), emoji, effect_id, reply_markup, +6 more.

send_documentC

Send a general file (document).

Inputs: chat_id (required), document (required), caption, effect_id, +11 more.

send_gameD

Send a game.

Inputs: chat_id (required), game_short_name (required), effect_id, reply_markup, +6 more.

send_giftC

Send a gift to a user or channel chat.

Inputs: gift_id (required), text, chat_id, user_id, +3 more.

send_invoiceC

Send an invoice for payment.

Inputs: title (required), chat_id (required), payload (required), currency (required), +25 more.

send_locationC

Send a point on the map.

Inputs: chat_id (required), latitude (required), longitude (required), heading, +11 more.

send_media_groupA

Send a group of photos, videos, documents, or audios as an album (2-10 items).

Inputs: chat_id (required), media, effect_id, reply_markup, +6 more.

send_messageB

Send a text message to a chat. Supports HTML, Markdown, MarkdownV2 formatting.

Inputs: text (required), chat_id (required), entities, effect_id, +9 more.

send_message_draftA

Send a streaming draft message. Content appears progressively as it's being generated.

Inputs: text (required), chat_id (required), entities, effect_id, +8 more.

send_paid_mediaB

Send paid media that requires Stars payment to view.

Inputs: chat_id (required), star_count (required), media, caption, +12 more.

send_photoB

Send a photo. Pass file_id, HTTP URL, or absolute file path.

Inputs: photo (required), chat_id (required), caption, effect_id, +11 more.

send_pollB

Send a poll or quiz. Supports v9.6 features: revoting, shuffle, user-added options, descriptions, multiple correct answers.

Inputs: chat_id (required), question (required), type, options, +25 more.

send_stickerC

Send a sticker.

Inputs: chat_id (required), sticker (required), emoji, effect_id, +7 more.

send_venueC

Send information about a venue.

Inputs: title (required), address (required), chat_id (required), latitude (required), +13 more.

send_videoC

Send a video file. Telegram clients support MPEG4 videos.

Inputs: video (required), chat_id (required), width, height, +16 more.

send_video_noteA

Send a video note (round video message, max 1 minute).

Inputs: chat_id (required), video_note (required), length, duration, +9 more.

send_voiceB

Send a voice message (.OGG encoded with OPUS).

Inputs: voice (required), chat_id (required), caption, duration, +10 more.

set_business_account_bioB
Idempotent

Set the bio of a business account.

Inputs: business_connection_id (required), bio.

set_business_account_gift_settingsB
Idempotent

Configure gift settings for a business account.

Inputs: business_connection_id (required), show_gift_button, accepted_gift_types.

set_business_account_nameC
Idempotent

Set the name of a connected business account.

Inputs: first_name (required), business_connection_id (required), last_name.

set_business_account_profile_photoC
Idempotent

Set the profile photo of a business account.

Inputs: business_connection_id (required), photo.

set_business_account_usernameC
Idempotent

Set the username of a business account.

Inputs: business_connection_id (required), username.

set_chat_administrator_custom_titleC
Idempotent

Set a custom title for an administrator.

Inputs: chat_id (required), user_id (required), custom_title (required).

set_chat_descriptionB
Idempotent

Change the description of a chat.

Inputs: chat_id (required), description.

set_chat_member_tagA
Idempotent

Set or remove a tag for a chat member (v9.5).

Inputs: chat_id (required), user_id (required), tag.

set_chat_menu_buttonA
Idempotent

Set the bot's menu button in a private chat or default menu button.

Inputs: chat_id, menu_button.

set_chat_permissionsA
Idempotent

Set default permissions for all members in a group/supergroup.

Inputs: chat_id (required), permissions, use_independent_chat_permissions.

set_chat_photoB
Idempotent

Set a new chat photo.

Inputs: photo (required), chat_id (required).

set_chat_sticker_setB
Idempotent

Set the sticker set for a supergroup.

Inputs: chat_id (required), sticker_set_name (required).

set_chat_titleB
Idempotent

Change the title of a chat.

Inputs: title (required), chat_id (required).

set_custom_emoji_sticker_set_thumbnailB
Idempotent

Set the thumbnail of a custom emoji sticker set.

Inputs: name (required), custom_emoji_id.

set_game_scoreC
Idempotent

Set the score of a user in a game.

Inputs: score (required), user_id (required), force, chat_id, +3 more.

set_message_reactionA
Idempotent

Set a reaction on a message. Use emoji or custom emoji.

Inputs: chat_id (required), message_id (required), is_big, reaction.

set_my_commandsC
Idempotent

Set the bot's command list shown in the menu.

Inputs: scope, commands, language_code.

set_my_default_administrator_rightsA
Idempotent

Set default admin rights requested when adding bot to groups/channels.

Inputs: rights, for_channels.

set_my_descriptionA
Idempotent

Set the bot's description (shown in empty chat).

Inputs: description, language_code.

set_my_nameC
Idempotent

Set the bot's name.

Inputs: name, language_code.

set_my_profile_photoC
Idempotent

Set the bot's profile photo (v9.4).

Inputs: photo.

set_my_short_descriptionA
Idempotent

Set the bot's short description (shown on profile page).

Inputs: language_code, short_description.

set_passport_data_errorsB
Idempotent

Inform a user that some Telegram Passport elements contain errors.

Inputs: user_id (required), errors.

set_sticker_emoji_listB
Idempotent

Change the list of emoji associated with a sticker.

Inputs: sticker (required), emoji_list (required).

set_sticker_keywordsB
Idempotent

Change search keywords for a sticker.

Inputs: sticker (required), keywords.

set_sticker_mask_positionC
Idempotent

Change the mask position of a mask sticker.

Inputs: sticker (required), mask_position.

set_sticker_position_in_setB
Idempotent

Move a sticker to a specific position in the set.

Inputs: sticker (required), position (required).

set_sticker_set_thumbnailC
Idempotent

Set the thumbnail of a sticker set.

Inputs: name (required), user_id (required), thumbnail.

set_sticker_set_titleA
Idempotent

Set the title of a sticker set.

Inputs: name (required), title (required).

set_user_emoji_statusA
Idempotent

Set a custom emoji status for a user (requires bot to have appropriate rights).

Inputs: user_id (required), emoji_status_custom_emoji_id, emoji_status_expiration_date.

set_webhookC
Idempotent

Set a webhook URL for receiving updates.

Inputs: url (required), ip_address, certificate, secret_token, +3 more.

stop_message_live_locationB
Idempotent

Stop updating a live location message.

Inputs: chat_id, message_id, reply_markup, inline_message_id.

stop_pollB
Idempotent

Stop a poll in a chat.

Inputs: chat_id (required), message_id (required), reply_markup, business_connection_id.

transfer_business_account_starsA
Idempotent

Transfer Telegram Stars from a business account to the bot.

Inputs: star_count (required), business_connection_id (required).

transfer_giftC
Idempotent

Transfer a gift to another user (v9.0).

Inputs: owned_gift_id (required), new_owner_chat_id (required), business_connection_id (required).

unban_chat_memberB
Idempotent

Unban a previously banned user.

Inputs: chat_id (required), user_id (required), only_if_banned.

unban_chat_sender_chatA
Idempotent

Unban a previously banned channel chat.

Inputs: chat_id (required), sender_chat_id (required).

unhide_general_forum_topicB
Idempotent

Unhide the 'General' topic.

Inputs: chat_id (required).

unpin_all_chat_messagesB
Idempotent

Unpin all messages in a chat.

Inputs: chat_id (required).

unpin_all_forum_topic_messagesC
Idempotent

Unpin all messages in a forum topic.

Inputs: chat_id (required), message_thread_id (required).

unpin_all_general_forum_topic_messagesA
Idempotent

Unpin all messages in the 'General' topic.

Inputs: chat_id (required).

unpin_chat_messageA
Idempotent

Unpin a message in a chat.

Inputs: chat_id (required), message_id.

upgrade_giftC
Idempotent

Upgrade a gift to a unique gift (v9.0).

Inputs: owned_gift_id (required), business_connection_id (required).

upload_sticker_fileA
Idempotent

Upload a sticker file to Telegram for later use in createNewStickerSet.

Inputs: sticker (required), user_id (required), sticker_format (required).

verify_chatB
Idempotent

Verify a chat on behalf of the bot's organization.

Inputs: chat_id (required), custom_description.

verify_userC
Idempotent

Verify a user on behalf of the bot's organization.

Inputs: user_id (required), custom_description.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.9/5.0

    Scored across 173 tools

    Disambiguation4/5

    Tools map to distinct Telegram API actions and are mostly separable by resource and verb. Singular/plural variants like forward_message vs forward_messages and custom helpers like get_file vs download_file create minor overlap, but descriptions clarify their intended use.

    Naming Consistency4/5

    The dominant pattern is consistent snake_case verb_noun naming (get_, set_, send_, edit_, delete_, create_, etc.). A few standalone verbs like close, get_me, and log_out break the pattern slightly but are still predictable.

    Tool Count2/5

    At 173 tools, the server is dramatically over-scoped for typical MCP use. Even though Telegram's API is broad, this many tools creates a heavy selection burden and far exceeds the recommended 3-15 tool range.

    Completeness5/5

    The tool surface covers nearly every major Telegram Bot API area: messages, media, chat administration, stickers, payments, business accounts, stories, gifts, forums, invites, webhooks, inline mode, and bot configuration. There are no obvious dead ends in the core workflows.

    Maintenance

    ActivityNo data
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that wraps the Telegram Bot API into semantic tools for LLM agents, supporting multi-bot management for sending and receiving messages. It enables agents to send text, photos, and documents, as well as fetch recent updates from multiple configured Telegram bots.
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Full-featured Telegram Bot API server for MCP (Model Context Protocol). 174 tools covering the entire Bot API — messages, chats, stickers, payments, forums, stories, and more.
      100
      7
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP server that exposes a Telegram bot, enabling sending messages and retrieving updates through natural language.
      3
      29 PyPI
      1
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      An MCP server for interacting with Telegram bots and channels using the Telegraf library. It allows AI agents to send messages, manage channels, forward content, and intelligently respond to Telegram conversations.
      5
      8
      -