@overpod/mcp-telegram

Archive or unarchive a Telegram dialog (moves to/from the Archive folder)

Ban a user from a supergroup or channel (permanent until unbanned)

Unban a previously banned user from a supergroup or channel

Edit a group's title, description, or photo

Promote a user to admin in a supergroup or channel with full permissions

List Telegram chats with unread counts, type indicators, and contact status

Search for Telegram chats, users, or channels by name or username. Returns description and member count

Get detailed info about a Telegram chat including name, type, members, description, and forum status

Get members of a Telegram group or channel

Get the current user's role in a chat (creator, admin, or member)

Create a new Telegram group or supergroup

Join a Telegram group or channel by username or invite link

Leave a Telegram group or channel

Invite users to a Telegram group or channel

Kick a user from a Telegram group (removes without permanent ban)

Pin or unpin a Telegram dialog in the dialog list

Mark a Telegram dialog as unread (or clear the unread mark)

Get the admin action log (recent event history) of a supergroup or channel. Includes bans, edits, pins, and role changes

Remove admin rights from a user in a supergroup or channel

Set the default permissions for all non-admin members of a group, supergroup, or channel. Omitted flags keep their current state; true = allowed, false = denied

Set slow mode for a supergroup (minimum interval between messages per user). Allowed values: 0, 10, 30, 60, 300, 900, 3600 seconds (0 disables slow mode)

Enable or disable author signatures on broadcast channel posts. Channel admin required; not supported for supergroups

Enable or disable aggressive anti-spam filtering in a supergroup. Supergroup only (not broadcast channels); requires admin with ban_users permission

Enable or disable forum/topics mode in a supergroup. Supergroup only; requires creator or admin.

Toggle pre-history visibility for new members in a supergroup. When hidden=true, new joiners cannot see messages posted before they joined. Supergroup only; requires admin

Approve or deny a pending join request for a supergroup or channel (basic groups are not supported). Admin with invite_users permission required

Create a new forum topic in a forum-enabled supergroup

Edit a forum topic — rename, change icon emoji, open/close, or show/hide

Get broadcast channel statistics: followers, views/shares/reactions per post & story, notification percent, recent post interactions. Broadcast channels only (use telegram-get-megagroup-stats for supergroups). Admin rights required; some channels may require Telegram Premium to expose stats

Get supergroup statistics: members, messages, viewers, posters (current vs previous period), top posters/admins/inviters. Supergroups only (use telegram-get-broadcast-stats for broadcast channels). Admin rights required. Telegram rate-limits this endpoint to roughly 1 request per 30 minutes per channel — expect FLOOD_WAIT on rapid repeat calls

Delete a forum topic and all its message history

Get all stickers from a sticker set by its short name. Returns each sticker with index and emoji. Use the index with telegram-send-sticker to send a specific sticker

Search for sticker sets by name or keyword. Returns matching sticker pack names that can be used with telegram-get-sticker-set

List all sticker sets installed by the user. Returns pack names and short names for use with other sticker tools

Send a sticker from a sticker set to a chat. First use telegram-get-sticker-set to browse available stickers and find the index

Get recently used stickers. Returns each sticker with its list index and associated emoji

Check Telegram connection status

Login to Telegram via QR code. Returns QR image. IMPORTANT: pass the entire result to user without modifications.

Log out from Telegram completely. Revokes the session on Telegram servers (removes it from Settings → Devices), deletes the local session file, and disconnects. After this you must run telegram-login to re-authenticate.

List the user's premium boost slots (premium.GetMyBoosts). Each entry includes slot index, the peer it currently boosts (if any), the date the boost was applied, expiration timestamp, and cooldownUntilDate (when a slot can be reassigned). Premium users have multiple slots; non-Premium users typically have a single slot. Read-only.

Fetch the boost status of a channel/supergroup (premium.GetBoostsStatus). Returns current boost level, total boosts, progress to next level (currentLevelBoosts/nextLevelBoosts), giftBoosts, premiumAudience ratio, public boostUrl, and whether the current user is boosting (myBoost + myBoostSlots). Also includes any prepaidGiveaways attached to the chat. Read-only.

List the boosts applied to a channel/supergroup (premium.GetBoostsList). Returns paginated boost entries with id, userId (or undefined for anonymous gift boosts), date, expires, flags (gift, giveaway, unclaimed), optional giveawayMsgId, usedGiftSlug, multiplier, and stars. Requires channel admin permissions. Supports pagination via nextOffset and an optional gifts filter to show only gift boosts. Read-only.

Fetch the current Telegram Stars balance and recent activity for a peer (payments.GetStarsStatus). Pass 'me' / '@me' (or the user's own id) to inspect your own wallet, or a bot/channel peer you own/administrate. Returns {balance:{amount,nanos}, subscriptions?[], subscriptionsNextOffset?, subscriptionsMissingBalance?, history?[], nextOffset?}. Each transaction has id, stars, date, peer (kind: appStore|playMarket|premiumBot|fragment|ads|api|peer|unsupported), and flags (refund/pending/failed/gift/reaction). Use telegram-get-stars-transactions for full paginated history. Opt-in: register only when MCP_TELEGRAM_ENABLE_STARS=1. Read-only.

Fetch a paginated Telegram Stars transaction history for a peer (payments.GetStarsTransactions). Pass 'me'/'@me' (or your own user id) for your wallet, or a bot/channel peer you own/administrate. Filters: inbound (credits only), outbound (debits only), ascending (chronological; default descending), subscriptionId (scope to a single subscription). Paginate with offset (cursor string from a prior response's nextOffset) and limit (default 50). Returns {balance, history[], nextOffset?, subscriptions?[], ...} — same shape as telegram-get-stars-status but focused on transactions. Opt-in: register only when MCP_TELEGRAM_ENABLE_STARS=1. Read-only.

List all available Telegram Star Gifts that can be sent to other users. Returns gift ID, cost in Stars, conversion value, availability (for limited gifts), and upgrade cost. Opt-in: register only when MCP_TELEGRAM_ENABLE_STARS=1. Read-only.

List Star Gifts received by a user or chat. Pass 'me' for your own gifts. Supports pagination via offset/nextOffset and filtering flags. Returns gift ID, kind (regular/unique), stars cost, from-peer, date, and upgrade eligibility. Opt-in: register only when MCP_TELEGRAM_ENABLE_STARS=1. Read-only.

Show or hide a received Star Gift on your profile. Pass msgId for a gift received as a personal message (DM), or chatId + savedId for a gift in a chat/channel. Set unsave=true to hide the gift (remove from profile display). Opt-in: register only when MCP_TELEGRAM_ENABLE_STARS=1.

Convert a received Star Gift into Stars (non-reversible). The gift is removed from your profile and its conversion value is added to your Stars balance. Pass msgId for personal gifts or chatId + savedId for chat gifts. Opt-in: register only when MCP_TELEGRAM_ENABLE_STARS=1.

List available Telegram Stars top-up tiers (from payments.GetStarsTopupOptions). Returns each option with star count, currency, price amount (in smallest currency units), and whether it is an extended/premium tier. Opt-in: register only when MCP_TELEGRAM_ENABLE_STARS=1. Read-only.

List active Telegram Stars subscriptions for a peer (payments.GetStarsSubscriptions). Pass 'me' for your own account or a bot/channel you own. Returns subscription ID, peer, renewal date, period, price in Stars, and canceled status. Paginate with offset. Opt-in: register only when MCP_TELEGRAM_ENABLE_STARS=1. Read-only.

Cancel or restore a Telegram Stars subscription (payments.ChangeStarsSubscription). Pass canceled=true to cancel an active subscription before its next renewal, or false to restore a previously canceled one. Opt-in: register only when MCP_TELEGRAM_ENABLE_STARS=1.

List Telegram Business chat links configured for the account. Each entry includes the t.me/... link, the prefilled message, optional title (admin-facing label), views count, and entityCount. Requires Telegram Business — returns empty list when none configured.

Create a Telegram Business chat link (t.me/m/... deep-link that opens a chat with you pre-filled with a message). Returns JSON with link, slug, message, title, and views. Requires Telegram Business subscription.

Edit an existing Telegram Business chat link by its slug (the trailing segment after t.me/m/). Returns JSON with updated fields. Requires Telegram Business subscription.

Delete a Telegram Business chat link by its slug. Requires Telegram Business subscription.

Resolve a Telegram Business chat link by slug to see whose chat it opens and the pre-filled message. Returns JSON with peerId, peerType, message, and entityCount.

Set Telegram Business work hours — days and time ranges when your business is open. Requires Telegram Business subscription. Pass clear=true to disable the work hours display entirely.

Set Telegram Business physical location (address + optional geo coordinates). Requires Telegram Business subscription. Pass clear=true to remove.

Set Telegram Business greeting message — auto-reply sent to new conversations using a quick reply shortcut as template. Requires Telegram Business subscription. Pass clear=true to disable.

Set Telegram Business away message — auto-reply when you are offline or outside work hours. Uses a quick reply shortcut as template. Requires Telegram Business subscription. Pass clear=true to disable.

Set Telegram Business intro card — title and description shown to new users opening your chat, with an optional sticker. Requires Telegram Business subscription. Pass clear=true to remove.

Get fact-check annotations on channel messages. Fact-checks are added by independent fact-checkers in supported countries. Most messages will show no fact-check.

Add or update a fact-check annotation. Requires fact-checker privileges (limited to independent verifiers in supported countries).

Remove a fact-check annotation. Requires fact-checker privileges.

Pin a message in a Telegram chat

Unpin a message in a Telegram chat

Send a scheduled message to a Telegram chat. The message will be delivered at the specified time by Telegram servers

Create a poll in a Telegram chat (multiple choice or quiz mode)

List forum topics in a Telegram group with Topics enabled. Shows topic names, unread counts, and status

Read messages from a specific forum topic in a Telegram group

Fetch metadata + an optional initial slice of participants for the active group call (voice/video chat) attached to a chat (phone.GetGroupCall). Returns call info (id, accessHash, participantsCount, title, scheduleDate, recordStartDate, streamDcId, flags) plus a participant slice (peer, date, muted/left/self flags, source, volume, video/presentation indicators) and participantsNextOffset. Pass limit:0 (default) for metadata only. Opt-in: register only when MCP_TELEGRAM_ENABLE_GROUP_CALLS=1. Read-only.

List participants of the active group call (voice/video chat) attached to a chat with pagination (phone.GetGroupParticipants). Looks up the chat's current InputGroupCall automatically, then returns {count, participants[], nextOffset?, version}. Each participant includes peer, date, source, volume, muted/self/left/videoJoined flags, raise-hand rating, about text, and hasVideo/hasPresentation indicators. Pass offset from a prior call's nextOffset to paginate; pass ids (user/channel peers) or sources to filter to specific participants. Opt-in: register only when MCP_TELEGRAM_ENABLE_GROUP_CALLS=1. Read-only.

Send a message to a Telegram chat

Read recent messages from a Telegram chat with sender names, dates, media info, and reactions

Search messages in a specific Telegram chat by text

Search messages globally across all public Telegram chats and channels

Edit a previously sent message in Telegram

Delete messages in a Telegram chat

Forward messages between Telegram chats

Get chats with unread messages. Forums show per-topic unread breakdown

List scheduled messages in a Telegram chat

Delete scheduled messages in a Telegram chat

Get replies/comments under a Telegram channel post or discussion message

Get a t.me link to a specific message in a Telegram channel or supergroup

Get unread @mentions addressed to you in a Telegram chat. Marks all mentions as read on the server when all unread mentions fit within the requested limit.

Get messages with unread reactions on your posts in a Telegram chat. Marks all reactions as read on the server when all unread reactions fit within the requested limit.

Translate one or more Telegram messages to a target language (requires Telegram Premium). Consumes account translation quota.

Send a typing/upload indicator to a Telegram chat (or cancel it)

Mark a Telegram chat as read

Query an inline bot (like @gif, @bing) in a chat context and return the compact result list. Returns queryId, cacheTime, and results[{id,type,title?,description?,url?}]. The queryId is typically valid for ~60s and can be passed to telegram-inline-query-send to deliver a chosen result. Bot must be a real bot account

Send an inline bot result to a chat by queryId + resultId (as returned by telegram-inline-query). The queryId is valid for ~60s after the original query, so call this soon after telegram-inline-query. Returns the sent messageId (0 if not extractable from the update).

List the inline/reply keyboard buttons on a Telegram message with their (row, col) indices, type (e.g. KeyboardButtonCallback, KeyboardButtonUrl), label and type-specific fields (callback data as base64, url, switchQuery, userId, copyText, etc). Helper for telegram-press-button — call this first to discover indices and filter by type before pressing. Returns markupType='none' and empty buttons when the message has no keyboard

Press an inline keyboard callback button on a message. Identify the button by (row, column) from its replyMarkup, or pass raw callback_data as base64. URL, switch-inline, game and 2FA-password buttons are rejected with a clear error. Returns the bot's callback answer: {alert?, hasUrl?, nativeUi?, message?, url?, cacheTime}

Initialize the polling cursor by fetching the current Telegram updates state {pts, qts, date, seq, unreadCount}. Call once before telegram-get-updates; then persist {pts, qts, date} in your agent state and feed them into telegram-get-updates. The MCP server does NOT store the cursor — you do.

Fetch new messages, deleted messages, and other updates since a previously-known {pts, qts, date} cursor (from telegram-get-state or a prior call). Returns compact newMessages[], deletedMessageIds[], otherUpdates[] (className only), and the new cursor state. isFinal=false means more updates are queued — call again with the returned state. If Telegram reports the gap is too long, a fallback hint is returned suggesting to resync via telegram-read-messages per chat. Cursor is stateless — the agent must persist {pts, qts, date} between calls.

Fetch new messages and updates for a single channel/supergroup since a known per-channel pts cursor. Separate from the global cursor used by telegram-get-updates. Returns compact newMessages[], otherUpdates[], and new {pts, isFinal, timeout?}. If the channel gap is too long, Telegram returns a dialog snapshot — this tool forwards it and hints to resync via telegram-read-messages. Cursor is stateless — the agent stores pts.

For a channel post with comments enabled, returns the linked discussion-group info: discussionGroupId, discussionMsgId, unreadCount, readInboxMaxId, readOutboxMaxId, topMessage. Use discussionGroupId + discussionMsgId with telegram-send-message (replyTo=discussionMsgId) to post a comment.

List groups that can be linked as a discussion group to a channel you admin. Helper for channel admins setting up comment threads.

List who has read a message in a small group (≤100 members, ≤7 days old). Returns readers with userId, readAt timestamp. Does NOT work for channels or groups over 100 members (CHAT_TOO_BIG).

Vote in a poll by option index (single or multi-choice). Empty array retracts vote.

Get aggregated poll results: vote counts, percentages, quiz answer status

List users who voted for specific poll options (public polls only, paginated)

Close a poll permanently. This is a one-way operation — closed polls cannot be reopened.

Get when your recipient read your outgoing message in a private chat. Returns null/Not read yet if unread. Errors if the other side disabled read receipts (YOUR_PRIVACY_RESTRICTED / USER_PRIVACY_RESTRICTED).

Get your Telegram contacts list with phone numbers

Get detailed profile info of a Telegram user including bio, birthday, premium status, business info and more

Get incoming messages from non-contacts (contact requests). Shows who messaged you without being in your contacts, with message preview

Add a user to your Telegram contacts. Use this to accept contact requests from non-contacts

Block a Telegram user. Blocked users cannot send you messages

Unblock a previously blocked Telegram user

Report a chat as spam to Telegram

Send a voice note (audio recording) to a Telegram chat. Shows as a voice message with waveform UI.

Send a video note (round-shaped short video) to a Telegram chat. Shows as a circular video in the UI.

Send a contact card (phone number + name) to a Telegram chat.

Send an animated dice/game emoji to a Telegram chat. Returns the server-rolled value — useful for games,

Send a geographic location to a Telegram chat. Static pin by default; set livePeriod to share a live-updating location for N seconds.

Send a venue card (point-of-interest with title and address) to a Telegram chat.

Send an album (group) of 2-10 photos as a single grouped message. Media type is auto-detected

Request server-side transcription of a voice note or video note (Telegram Premium feature). Returns immediately with transcriptionId — if pending:true, call telegram-get-transcription to poll for completion.

Poll for updated transcription result. Calls the same endpoint as telegram-transcribe-audio — Telegram guarantees idempotency (returns same transcriptionId with updated text once processing completes).

Rate transcription quality (good/poor) to improve Telegram speech-to-text.

Mute or unmute notifications for a Telegram chat. Set muted=true to mute (optionally with duration in seconds), muted=false to unmute

Get list of your Telegram chat folders (filters) with their names and chat counts

Set auto-delete timer for messages in a chat. Common values: 86400 (1 day), 604800 (1 week), 2592000 (1 month). Use 0 to disable

Get list of all active Telegram sessions (logged-in devices) with device info, IP, and last active time

Terminate a specific Telegram session by its hash, or explicitly terminate all other sessions by setting terminateAllOther=true

Configure privacy settings for your Telegram account. Controls who can see your phone number, last seen, profile photo, etc.

Update your Telegram profile — first name, last name, bio, or username

Create a new invite link for a group or channel

Get list of invite links for a group or channel. By default returns links created by the current account; pass adminId to query another admin's links

Save or clear a message draft for a chat. Pass empty text to clear the draft. Optional replyTo sets the message being replied to

Get all saved message drafts across chats

Delete saved message drafts. Pass chatId to clear the draft for a single chat. Without chatId, clears drafts in ALL chats — requires confirmAllChats: true

Get Saved Messages dialogs (Telegram's per-sender grouping of messages forwarded to your Saved Messages)

Revoke an invite link for a group or channel

Set your profile emoji status (custom animated emoji shown next to your name). Requires Telegram Premium. Pass documentId or collectibleId to set — omit both to clear the status. Use telegram-list-emoji-statuses to browse available IDs.

List default or recently-used emoji statuses available for your account. Useful for finding a documentId to pass to telegram-set-emoji-status.

Clear your recently-used emoji status list (the 'recent' section in the emoji status picker).

Set your profile name color or profile background color. Requires Telegram Premium for colors above index 6 and for profile background patterns. Omit color to reset to default.

Set your birthday in your Telegram profile. Year is optional (omit to hide age). Pass clear=true to remove birthday. Requires day and month unless clearing.

Set the channel displayed on your profile as 'Personal Channel'. Pass clear=true to remove. Pass channelId or @username of a channel you own or are subscribed to.

Upload and set a new profile photo from a local file. Supports JPEG/PNG for static avatar or MP4 for animated avatar (square, up to 10s). Optionally set as fallback photo shown to users who cannot see your main photo.

Delete one or more profile photos by their photo IDs. Use telegram-get-profile-photo to obtain the current photo ID. Returns which IDs were deleted and which were not found.

Send a file (photo, document, video, etc.) to a Telegram chat

Download media from a Telegram message to a local file

Download profile photo of a Telegram user, group, or channel. Returns inline image or saves to file

Fetch Telegram's web-page preview metadata (type, title, description, site name) for a URL

Create a new Telegram chat folder (filter). Returns the new folder ID. Pass type flags to auto-include entire categories, or list specific chats in includePeers. Emoticon must be a single emoji character.

Edit an existing Telegram chat folder by its ID (from telegram-get-chat-folders). Only pass fields you want to change — omitted fields keep their current values.

Delete a Telegram chat folder by its ID. Chats inside the folder are not deleted — they remain in All Chats. System folders (0 = All Chats, 1 = Archive) cannot be deleted.

Reorder Telegram chat folders by specifying a new order of folder IDs. All existing custom folder IDs must be included.

Get Telegram's suggested chat folders based on your chat list (e.g. 'Unread', 'Personal', 'Work'). Returns folder templates you can create with telegram-create-folder.

Enable or disable folder tags (colored labels that appear on messages in chat lists when the message belongs to a tagged folder). Requires Telegram Premium.

Get your account-level global privacy settings: whether new non-contacts are auto-archived/muted, whether archived chats are kept unmuted, whether read receipts are hidden, and whether non-contacts must have Premium to message you.

Update account-level global privacy settings. Only pass the fields you want to change — omitted fields keep their current values. hideReadMarks and newNoncontactPeersRequirePremium require Telegram Premium.

Send emoji reaction(s) to a message. Supports multiple reactions and adding to existing ones. Omit emoji to remove all reactions

Get detailed reaction info for a message: which reactions, counts, and who reacted (when visible)

Set the default emoji reaction used in quick-reaction menus across Telegram

Get the list of most popular emoji reactions available on Telegram

Set which reactions are available in a chat. type='all' allows all standard emoji (set allowCustom=true to also permit custom emoji for Premium users), type='some' restricts to a specific emoji list, type='none' disables reactions entirely. Requires admin

Get the list of emoji reactions the current account used recently

Send a paid reaction (★ Stars) on a channel post. Stars are spent from your balance. Optional private flag controls leaderboard visibility.

Change leaderboard visibility of your paid reaction on a specific channel post (Layer 198 API).

Get your current default paid reaction privacy setting.

Fetch active stories from contacts/channels the user follows. Pagination via 'next' + 'state' — pass the returned state back on the next call with next:true to load more. Use hidden:true to read stories from muted/archived peers. Returns compact story metadata (id, date, expireDate, caption, mediaType, counters) without raw media blobs.

Fetch currently active stories posted by a specific peer (user/channel). Returns compact story metadata (id, date, expireDate, caption, mediaType, counters) with media type className only — no raw media blobs. Use telegram-download-media with the story id if you need media bytes.

Fetch specific stories from a peer by their numeric IDs. Useful for retrieving archived/pinned stories outside the active feed. Returns compact story metadata and optional pinnedToTop list. Pass up to ~100 ids per request.

List viewers of one of YOUR stories (stories.GetStoryViewsList). Returns per-viewer entries (user id, view date, their reaction emoji if any), plus totals (viewsCount, forwardsCount, reactionsCount) and nextOffset for pagination. Pass your own user id (numeric) or @username as the peer — this only works for stories you posted. Some accounts (non-Premium, old stories) may not get a full viewer list — a Premium hint is surfaced on typical errors.

Publish a new story (photo or video) to your profile or a channel you manage. Privacy: everyone/contacts/close_friends/selected (allowUserIds required for 'selected'). MediaAreas not supported in this version.

Edit an existing story: replace media, update caption ('' clears it), or change privacy rules.

Delete one or more of your own stories. This action is irreversible and requires confirm:true.

React to a story with an emoji, or remove the current reaction by passing ''.

Get a shareable t.me/… URL for a public story.

Mark stories as seen up to a given story ID (maxId, inclusive).

Pin or unpin stories in your profile highlights (Telegram allows up to 3 pinned stories).

Pin stories to the very top of your pinned row. Pass an empty array [] to clear all top-pinned stories.

Hide your story views retroactively (past=true) and/or for the next 25 minutes (future=true). Requires Telegram Premium — non-Premium accounts receive PREMIUM_ACCOUNT_REQUIRED.

Fetch auto-archived (expired) stories from a peer's archive. Paginate via offsetId (pass last story id from previous page).

Report a story via the multi-step option flow. First call with option:'' starts the flow; subsequent calls pass the base64 option bytes from the previous response.

Fetch the list of quick-reply shortcuts configured for the user account (messages.GetQuickReplies). Each entry has {shortcutId, shortcut, topMessage, count} — use the shortcutId with telegram-get-quick-reply-messages to inspect the stored messages. Optional `hash` implements Telegram's hash-based diff: pass the last-known aggregate hash as a decimal string and the server may respond with {notModified:true} if nothing changed. Opt-in: register only when MCP_TELEGRAM_ENABLE_QUICK_REPLIES=1. Read-only.

Fetch messages stored under a quick-reply shortcut (messages.GetQuickReplyMessages). Use `shortcutId` from telegram-get-quick-replies. Optional `ids` narrows to specific message ids within the shortcut. Optional `hash` implements Telegram's hash-based diff: pass the last-known aggregate hash as a decimal string — the server may respond with {notModified:true, count} if nothing changed. Returns compact {count, messages[{id, date, text, isService, fromId?, replyToMsgId?}]}. Opt-in: register only when MCP_TELEGRAM_ENABLE_QUICK_REPLIES=1. Read-only.