telegram-api-mcp
This server is a comprehensive MCP interface to the Telegram Bot API v10.2, exposing all 185 methods for messaging, chat and user management, media, stickers, forums, and more.
Messaging: Send text with HTML/Markdown/MarkdownV2 formatting; rich messages up to 32,768 characters with headings, tables, lists, collages, footnotes, and up to 50 inline media; photos, audio, documents, videos, animations, voice notes, video notes, paid media, media groups, locations, venues, contacts, polls, dice, stickers, and checklists; set chat actions and message reactions; forward/copy messages.
Message editing/deletion: Edit text, captions, media, reply markup, live locations, and checklists; stop polls; delete single or multiple messages.
Chat and member management: Get chat info, administrators, member counts, and members; ban/unban/restrict/promote users; set custom admin titles and tags; manage chat photos, titles, descriptions, permissions, and sticker sets; pin/unpin messages; leave chat.
Invite links and join requests: Create, edit, revoke, and export invite links; create subscription invite links; approve/decline join requests; get user chat boosts.
Forum topics: Create, edit, close, reopen, and delete topics; manage the general topic; pin/unpin and unpin all messages in topics.
Bot self-management: getMe, log out, close; set/get commands, name, description, short description, and default administrator rights; manage profile photo; get user profile photos and audio tracks.
Stickers and files: Send stickers, get sticker sets, get custom emoji stickers, upload sticker files, create/add to sticker sets; get file info for downloads.
Updates & webhooks: Get updates, set/delete webhooks, get webhook info (available via meta-mode).
Meta-mode: Use only
telegram_findandtelegram_callto access all 185 methods with ~99% context token savings.Formatting guidance: Built-in
telegram_formattool and resources explain syntax for rich messages, media, and reply markup.Reliability & security: Rate limiting (global and per-chat), circuit breaker with auto-recovery, retries with exponential backoff respecting Telegram 429, Zod validation, token masking, file upload path traversal protection, and response truncation.
Provides full access to 169 Telegram Bot API methods for managing messages, media, polls, chats, forums, stickers, payments, business, stories, gifts, games, inline, managed bots, and more.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@telegram-api-mcp send a poll 'Best language?' with options Python, JavaScript, Rust"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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_formattool — the server explains the exact shape ofrich_message,media,reply_markup,polland more before you send, so an agent never has to guess the syntax (also exposed as MCP resources undertelegram://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 5xxZod 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:refreshre-downloads the official spec,npm run auditfails if any method or parameter drifts from itResponse 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_tokenWith meta-mode (recommended for large conversations):
claude mcp add telegram -- npx telegram-api-mcp \
-e TELEGRAM_BOT_TOKEN=your_token \
-e TELEGRAM_META_MODE=trueClaude 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.jsEnvironment Variables
Variable | Required | Default | Description |
| Yes | — | Bot token from @BotFather |
| No | — | Default chat ID for all tools |
| No | — | Default forum topic thread ID |
| No |
| Use 2 meta-tools instead of 185 |
| No |
| Max requests/sec (Telegram limit) |
| No |
| Max messages/min per group (Telegram limit) |
| No |
| Retry attempts on transient errors |
| No |
| Failures before circuit opens |
| No |
| Circuit breaker cooldown (ms) |
| No | — | Comma-separated allowed upload paths |
| No |
| 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 categorytelegram_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).

| 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 mirrorDesign 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 andscripts/audit-registry.mjsdiffs 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(), noFunction(), no dynamic importsNo external requests except
api.telegram.orgNo 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 mirrorOther Projects by @timoncool
Project | Description |
Civitai API as MCP server | |
TRAIL — cross-MCP content tracking protocol | |
AI music studio — songs, vocals, covers, videos | |
AI video production in the browser | |
AI anti-spam bot for Telegram | |
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:
1E7dHL22RpyhJGVpcvKdbyZgksSYkYeEBCETH (ERC20):
0xb5db65adf478983186d4897ba92fe2c25c594a0cUSDT (TRC20):
TQST9Lp2TjK6FiVkn4fwfGUee7NmkxEE7C
Star History
License
MIT
Available Tools
173 toolsadd_sticker_to_setCIdempotent
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_requestAIdempotent
Approve a chat join request.
Inputs: chat_id (required), user_id (required).
approve_suggested_postCIdempotent
Approve a suggested post for a channel (v9.2).
Inputs: message_id (required), business_connection_id (required).
ban_chat_memberADestructive
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_chatADestructive
Ban a channel chat from sending messages in a supergroup.
Inputs: chat_id (required), sender_chat_id (required).
closeAIdempotent
Close the bot instance. Use before moving between local servers.
Inputs: no named parameters.
close_forum_topicAIdempotent
Close an open topic in a forum supergroup.
Inputs: chat_id (required), message_thread_id (required).
close_general_forum_topicCIdempotent
Close the 'General' topic.
Inputs: chat_id (required).
convert_gift_to_starsCIdempotent
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_chat_invite_linkC
Create an additional invite link.
Inputs: chat_id (required), name, expire_date, member_limit, +1 more.
create_chat_subscription_invite_linkA
Create a subscription invite link for a channel chat.
Inputs: chat_id (required), subscription_price (required), subscription_period (required), name.
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_invoice_linkC
Create a link for an invoice.
Inputs: title (required), payload (required), currency (required), description (required), +3 more.
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_requestBIdempotent
Decline a chat join request.
Inputs: chat_id (required), user_id (required).
decline_suggested_postCIdempotent
Decline a suggested post for a channel (v9.2).
Inputs: message_id (required), business_connection_id (required).
delete_business_messagesBDestructive
Delete business messages.
Inputs: message_ids (required), business_connection_id (required).
delete_chat_photoADestructive
Delete a chat photo.
Inputs: chat_id (required).
delete_chat_sticker_setADestructive
Delete the sticker set from a supergroup.
Inputs: chat_id (required).
delete_forum_topicADestructive
Delete a forum topic along with all its messages.
Inputs: chat_id (required), message_thread_id (required).
delete_messageADestructive
Delete a message. Bot must have delete rights in the chat.
Inputs: chat_id (required), message_id (required).
delete_messagesADestructive
Delete multiple messages at once. Max 100 messages.
Inputs: chat_id (required), message_ids (required).
delete_my_commandsBDestructive
Delete the bot's command list for a given scope and language.
Inputs: scope, language_code.
delete_sticker_from_setCDestructive
Delete a sticker from a set.
Inputs: sticker (required).
delete_sticker_setADestructive
Delete a sticker set created by the bot.
Inputs: name (required).
delete_storyCDestructive
Delete a story (v9.0).
Inputs: story_id (required), business_connection_id (required).
delete_webhookADestructive
Remove webhook integration and switch back to getUpdates.
Inputs: drop_pending_updates.
download_fileAIdempotent
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_chat_invite_linkBIdempotent
Edit a non-primary invite link.
Inputs: chat_id (required), invite_link (required), name, expire_date, +2 more.
edit_chat_subscription_invite_linkCIdempotent
Edit a subscription invite link.
Inputs: chat_id (required), invite_link (required), name.
edit_forum_topicAIdempotent
Edit name and icon of a forum topic.
Inputs: chat_id (required), message_thread_id (required), name, icon_custom_emoji_id.
edit_general_forum_topicAIdempotent
Edit the name of the 'General' forum topic.
Inputs: name (required), chat_id (required).
edit_message_captionAIdempotent
Edit the caption of a media message.
Inputs: caption, chat_id, message_id, parse_mode, +4 more.
edit_message_checklistCIdempotent
Edit a checklist message (v9.1).
Inputs: chat_id (required), message_id (required), checklist, reply_markup.
edit_message_live_locationCIdempotent
Edit a live location message.
Inputs: latitude (required), longitude (required), chat_id, heading, +5 more.
edit_message_mediaAIdempotent
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_markupCIdempotent
Edit the inline keyboard of a message.
Inputs: chat_id, message_id, reply_markup, inline_message_id.
edit_message_textAIdempotent
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_storyCIdempotent
Edit a posted story (v9.0).
Inputs: story_id (required), business_connection_id (required), areas, caption, +3 more.
edit_user_star_subscriptionCIdempotent
Edit a user's Star subscription (cancel or extend).
Inputs: user_id (required), is_canceled (required), telegram_payment_charge_id (required).
export_chat_invite_linkADestructive
Generate a new primary invite link (revokes previous one).
Inputs: chat_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_giftsARead-onlyIdempotent
Get the list of gifts that can be sent.
Inputs: no named parameters.
get_business_account_giftsBRead-onlyIdempotent
Get gifts received by a business account.
Inputs: business_connection_id (required), exclude_from_blockchain.
get_business_account_star_balanceARead-onlyIdempotent
Get the Telegram Stars balance of a business account.
Inputs: business_connection_id (required).
get_business_connectionCRead-onlyIdempotent
Get information about a business connection.
Inputs: business_connection_id (required).
get_chatARead-onlyIdempotent
Get full information about a chat (title, description, photo, member count, permissions, etc).
Inputs: chat_id (required).
get_chat_administratorsARead-onlyIdempotent
Get a list of administrators in a chat.
Inputs: chat_id (required).
get_chat_giftsARead-onlyIdempotent
Get gifts received by a chat (v9.3).
Inputs: chat_id (required).
get_chat_memberBRead-onlyIdempotent
Get information about a member in a chat.
Inputs: chat_id (required), user_id (required).
get_chat_member_countARead-onlyIdempotent
Get the number of members in a chat.
Inputs: chat_id (required).
get_custom_emoji_stickersARead-onlyIdempotent
Get information about custom emoji stickers by their identifiers.
Inputs: custom_emoji_ids (required).
get_fileARead-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_stickersARead-onlyIdempotent
Get custom emoji stickers that can be used as forum topic icons.
Inputs: no named parameters.
get_game_high_scoresCRead-onlyIdempotent
Get high scores for a game.
Inputs: user_id (required), chat_id, message_id, inline_message_id.
get_managed_bot_tokenARead-onlyIdempotent
Get the token of a managed bot (v9.6).
Inputs: user_id (required).
get_meARead-onlyIdempotent
Get basic information about the bot (id, name, username, etc).
Inputs: no named parameters.
get_my_commandsARead-onlyIdempotent
Get the bot's current command list.
Inputs: scope, language_code.
get_my_default_administrator_rightsBRead-onlyIdempotent
Get default admin rights.
Inputs: for_channels.
get_my_descriptionBRead-onlyIdempotent
Get the bot's description.
Inputs: language_code.
get_my_nameARead-onlyIdempotent
Get the bot's name for a given language.
Inputs: language_code.
get_my_short_descriptionBRead-onlyIdempotent
Get the bot's short description.
Inputs: language_code.
get_my_star_balanceARead-onlyIdempotent
Get the bot's Telegram Stars balance (v9.1).
Inputs: no named parameters.
get_star_transactionsCRead-onlyIdempotent
Get the bot's Telegram Star transactions.
Inputs: limit, offset.
get_sticker_setARead-onlyIdempotent
Get a sticker set by name.
Inputs: name (required).
get_trailARead-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_statsARead-onlyIdempotent
Get summary statistics from the TRAIL content log.
Inputs: since, requester.
get_updatesARead-onlyIdempotent
Receive incoming updates via long polling.
Inputs: limit, offset, timeout, allowed_updates.
get_user_chat_boostsARead-onlyIdempotent
Get a user's boosts in a chat.
Inputs: chat_id (required), user_id (required).
get_user_giftsBRead-onlyIdempotent
Get gifts received by a user (v9.3).
Inputs: user_id (required).
get_user_profile_audiosBRead-onlyIdempotent
Get a user's profile audio tracks (v9.4).
Inputs: user_id (required), limit, offset.
get_user_profile_photosCRead-onlyIdempotent
Get a user's profile photos.
Inputs: user_id (required), limit, offset.
get_webhook_infoARead-onlyIdempotent
Get current webhook status.
Inputs: no named parameters.
hide_general_forum_topicBIdempotent
Hide the 'General' topic.
Inputs: chat_id (required).
leave_chatADestructive
Bot leaves a group, supergroup, or channel.
Inputs: chat_id (required).
log_outAIdempotent
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_messageCIdempotent
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_memberBIdempotent
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_messageCIdempotent
Mark a business message as read.
Inputs: chat_id (required), message_id (required), business_connection_id (required).
refund_star_paymentCIdempotent
Refund a Telegram Star payment.
Inputs: user_id (required), telegram_payment_charge_id (required).
remove_business_account_profile_photoCIdempotent
Remove a business account profile photo.
Inputs: business_connection_id (required), photo_id.
remove_chat_verificationBIdempotent
Remove chat verification.
Inputs: chat_id (required).
remove_my_profile_photoCIdempotent
Remove the bot's profile photo (v9.4).
Inputs: photo_id.
remove_user_verificationBIdempotent
Remove user verification.
Inputs: user_id (required).
reopen_forum_topicBIdempotent
Reopen a closed topic.
Inputs: chat_id (required), message_thread_id (required).
reopen_general_forum_topicAIdempotent
Reopen the 'General' topic.
Inputs: chat_id (required).
replace_managed_bot_tokenAIdempotent
Replace the token of a managed bot (v9.6).
Inputs: user_id (required).
replace_sticker_in_setBIdempotent
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_memberBIdempotent
Restrict a user's permissions in a supergroup.
Inputs: chat_id (required), user_id (required), until_date, permissions, +1 more.
revoke_chat_invite_linkCDestructive
Revoke an invite link.
Inputs: chat_id (required), invite_link (required).
save_prepared_inline_messageBIdempotent
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_buttonBIdempotent
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_bioBIdempotent
Set the bio of a business account.
Inputs: business_connection_id (required), bio.
set_business_account_gift_settingsBIdempotent
Configure gift settings for a business account.
Inputs: business_connection_id (required), show_gift_button, accepted_gift_types.
set_business_account_nameCIdempotent
Set the name of a connected business account.
Inputs: first_name (required), business_connection_id (required), last_name.
set_business_account_profile_photoCIdempotent
Set the profile photo of a business account.
Inputs: business_connection_id (required), photo.
set_business_account_usernameCIdempotent
Set the username of a business account.
Inputs: business_connection_id (required), username.
set_chat_administrator_custom_titleCIdempotent
Set a custom title for an administrator.
Inputs: chat_id (required), user_id (required), custom_title (required).
set_chat_descriptionBIdempotent
Change the description of a chat.
Inputs: chat_id (required), description.
set_chat_member_tagAIdempotent
Set or remove a tag for a chat member (v9.5).
Inputs: chat_id (required), user_id (required), tag.
set_chat_permissionsAIdempotent
Set default permissions for all members in a group/supergroup.
Inputs: chat_id (required), permissions, use_independent_chat_permissions.
set_chat_photoBIdempotent
Set a new chat photo.
Inputs: photo (required), chat_id (required).
set_chat_sticker_setBIdempotent
Set the sticker set for a supergroup.
Inputs: chat_id (required), sticker_set_name (required).
set_chat_titleBIdempotent
Change the title of a chat.
Inputs: title (required), chat_id (required).
set_custom_emoji_sticker_set_thumbnailBIdempotent
Set the thumbnail of a custom emoji sticker set.
Inputs: name (required), custom_emoji_id.
set_game_scoreCIdempotent
Set the score of a user in a game.
Inputs: score (required), user_id (required), force, chat_id, +3 more.
set_message_reactionAIdempotent
Set a reaction on a message. Use emoji or custom emoji.
Inputs: chat_id (required), message_id (required), is_big, reaction.
set_my_commandsCIdempotent
Set the bot's command list shown in the menu.
Inputs: scope, commands, language_code.
set_my_default_administrator_rightsAIdempotent
Set default admin rights requested when adding bot to groups/channels.
Inputs: rights, for_channels.
set_my_descriptionAIdempotent
Set the bot's description (shown in empty chat).
Inputs: description, language_code.
set_my_nameCIdempotent
Set the bot's name.
Inputs: name, language_code.
set_my_profile_photoCIdempotent
Set the bot's profile photo (v9.4).
Inputs: photo.
set_my_short_descriptionAIdempotent
Set the bot's short description (shown on profile page).
Inputs: language_code, short_description.
set_passport_data_errorsBIdempotent
Inform a user that some Telegram Passport elements contain errors.
Inputs: user_id (required), errors.
set_sticker_emoji_listBIdempotent
Change the list of emoji associated with a sticker.
Inputs: sticker (required), emoji_list (required).
set_sticker_keywordsBIdempotent
Change search keywords for a sticker.
Inputs: sticker (required), keywords.
set_sticker_mask_positionCIdempotent
Change the mask position of a mask sticker.
Inputs: sticker (required), mask_position.
set_sticker_position_in_setBIdempotent
Move a sticker to a specific position in the set.
Inputs: sticker (required), position (required).
set_sticker_set_thumbnailCIdempotent
Set the thumbnail of a sticker set.
Inputs: name (required), user_id (required), thumbnail.
set_sticker_set_titleAIdempotent
Set the title of a sticker set.
Inputs: name (required), title (required).
set_user_emoji_statusAIdempotent
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_webhookCIdempotent
Set a webhook URL for receiving updates.
Inputs: url (required), ip_address, certificate, secret_token, +3 more.
stop_message_live_locationBIdempotent
Stop updating a live location message.
Inputs: chat_id, message_id, reply_markup, inline_message_id.
stop_pollBIdempotent
Stop a poll in a chat.
Inputs: chat_id (required), message_id (required), reply_markup, business_connection_id.
transfer_business_account_starsAIdempotent
Transfer Telegram Stars from a business account to the bot.
Inputs: star_count (required), business_connection_id (required).
transfer_giftCIdempotent
Transfer a gift to another user (v9.0).
Inputs: owned_gift_id (required), new_owner_chat_id (required), business_connection_id (required).
unban_chat_memberBIdempotent
Unban a previously banned user.
Inputs: chat_id (required), user_id (required), only_if_banned.
unban_chat_sender_chatAIdempotent
Unban a previously banned channel chat.
Inputs: chat_id (required), sender_chat_id (required).
unhide_general_forum_topicBIdempotent
Unhide the 'General' topic.
Inputs: chat_id (required).
unpin_all_chat_messagesBIdempotent
Unpin all messages in a chat.
Inputs: chat_id (required).
unpin_all_forum_topic_messagesCIdempotent
Unpin all messages in a forum topic.
Inputs: chat_id (required), message_thread_id (required).
unpin_all_general_forum_topic_messagesAIdempotent
Unpin all messages in the 'General' topic.
Inputs: chat_id (required).
unpin_chat_messageAIdempotent
Unpin a message in a chat.
Inputs: chat_id (required), message_id.
upgrade_giftCIdempotent
Upgrade a gift to a unique gift (v9.0).
Inputs: owned_gift_id (required), business_connection_id (required).
upload_sticker_fileAIdempotent
Upload a sticker file to Telegram for later use in createNewStickerSet.
Inputs: sticker (required), user_id (required), sticker_format (required).
verify_chatBIdempotent
Verify a chat on behalf of the bot's organization.
Inputs: chat_id (required), custom_description.
verify_userCIdempotent
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
Scored across 173 tools
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.
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.
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.
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
Related MCP Connectors
Hosted Telegram MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Telegram bridge for your MCP-compatible agent. Bidirectional, no LLM in our stack.
Multi-tenant Telegram gateway for AI agents — HTTP+stdio, 8 tools, MTProto User API
MCP server for Gainium — manage trading bots, deals, and balances via AI assistants
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn 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
- AlicenseBqualityDmaintenanceFull-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.1007MIT
- AlicenseAqualityDmaintenanceMCP server that exposes a Telegram bot, enabling sending messages and retrieving updates through natural language.329 PyPI1MIT
- FlicenseAqualityDmaintenanceAn 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.58-