MCP Telegram

Return the Telegram accounts currently signed in on this machine.

Open a browser window where the user signs in to Telegram (phone → code → 2FA). Resolves once the user finishes. Use this when no account is signed in or to add another one.

Drop the local session for an account and revoke it on the Telegram side.

Return the profile of the authenticated user for the chosen account.

Open a local browser tab where the user can toggle read-only mode and edit the tool allowlist / blocklist. Resolves when the user closes the tab. Changes are persisted to ~/.telegram-agent/state.json; the MCP client must be restarted to pick them up. Env vars (MCP_TELEGRAM_READONLY / TOOLS / DISABLE) override stored values and are shown as locked in the UI.

Change own first name, last name, or about. Omitted fields are left untouched.

Set or clear (empty string) own public username.

Set the account birthday. Year is optional.

Upload a new profile photo from a local path or URL.

List available Telegram dialogs, chats and channels for the chosen account.

Find dialogs by a substring against their name/title/username.

Look up a user, channel, or chat by @username.

Return the user-defined folders (a.k.a. chat filters) with their inclusion rules.

List messages in a dialog. Newest first.

Search messages within one dialog. Supports text substring, type filter (photos/links/etc), sender filter, and date range. Newest first unless reverse=true.

Search messages across every chat the user is in. Useful for "find that link about X".

Fetch one or several messages from a dialog by their ids.

Mark a dialog (and optionally up to a specific message id) as read.

Send a text message to a dialog. Supports reply, forum topic, silent, scheduled delivery, and parse mode.

Edit the text of a previously sent message.

Delete messages by id. `revoke` (default true) deletes for all participants where possible.

Forward messages from one dialog to another.

Pin a message in the dialog.

Unpin a specific message, or pass no id to unpin everything in the dialog.

Send a Telegram message to someone identified only by their phone number. The phone is briefly added to contacts (Telegram requires this), the message is sent, then the contact entry is removed by default. Phone must include country code (e.g. +12025550123).

Return all reaction-tags the user has set on Saved Messages, with their custom titles and per-tag message counts. Premium feature; works only on the `me` peer.

Set or clear the custom title of a Saved-Messages reaction-tag. Pass `title` to rename, omit to clear. Premium feature.

Server-suggested default emoji set for Saved-Messages tagging.

Search inside Saved Messages (`me`). Combine free-text `query` with `tagEmoji` and/or `tagCustomEmojiIds` to filter by reaction-tag. Newest first.

List the forum-style sub-dialogs inside Saved Messages — each grouping forwards from one origin peer.

Fetch messages inside one Saved-Messages sub-dialog (filtered by original sender peer).

Wipe all messages in one Saved-Messages sub-dialog (forwards from a single origin peer). Irreversible.

Pin/unpin one of the forum-style sub-dialogs inside Saved Messages.

Upload and send one or more files. Each path may be an absolute local path or an `https://` URL. Passing multiple paths sends them as an album.

Download the media attached to a message. Files land in /tmp/mcp-tools-sandbox-AhdMoJ/.telegram-agent/downloads (override with MCP_TELEGRAM_DOWNLOADS env). Returns the absolute path.

Download the profile photo of a user/chat/channel. Saved under /tmp/mcp-tools-sandbox-AhdMoJ/.telegram-agent/downloads.

Request a transcription of a voice note or video message. Requires a Telegram Premium account. The response may be pending — re-call to poll, passing the same message id.

Set one or more reactions on a message. Pass an empty reaction list to remove existing reactions.

Fetch the current reactions for one or more messages in a dialog.

Set the quick reaction emoji shown on long-press in clients.

Send a poll. For a quiz, set `quiz: true` and `correctAnswerIndex` (0-based). Use `closePeriod` (seconds) or `closeDate` (unix seconds) to auto-close.

Cast a vote on a poll by the index(es) of the chosen options.

Finalize a poll so no further votes are accepted.

Fetch the current vote tally for a poll message.

Return the stories feed (other users' active stories).

Return active stories posted by one peer.

Publish a story (photo or video) on the chosen peer. Visibility defaults to "everyone".

Remove stories you previously posted.

Increment view counters for the given stories.

Show who has viewed a story you posted.

Fully ban a user. Pass `untilDate` (unix seconds) to time-limit the ban; default is forever.

Remove all restrictions for a user.

Set specific restrictions. `true` for a field means the user CANNOT do that action.

Grant admin rights. Pass only the fields you want enabled; omitted fields default to false.

Remove all admin rights from a user.

Add a user (or list of users) to a channel or supergroup.

Return role, rights, and join date for one user in a channel/supergroup.

List members of a group, supergroup, or channel. Optional filter (admins/kicked/banned/bots) and substring search.

Wipe every message a given user has posted in the channel/supergroup.

Remove a user from a chat/channel. Requires admin rights.

Return recent admin events. Set fields in `events` to `true` to include those categories; leave empty to include everything.

Set a new title. Works for channels, supergroups, and basic groups.

Set the description of a channel/supergroup. Max 255 chars.

Upload a new avatar photo from a local path or URL.

Assign a new public username. Pass an empty string to clear it.

Verify whether a desired channel/supergroup username is free.

Limit how often non-admins can post. Allowed values: 0 (off), 10, 30, 60, 300, 900, 3600 seconds.

Broadcast channels only.

Supergroups only. When enabled, new members cannot see history before they joined.

When enabled, new members must be approved by an admin.

Leave the channel. Use `delete_channel` to also remove it (creator only).

Return extended info for a channel or supergroup (about, participants count, linked chat, slow mode).

Return extended profile info (bio, common chats count, etc.) for a user.

Create a broadcast channel (`broadcast: true`) or a supergroup (`megagroup: true`).

Permanently delete the channel. Creator only.

One-way migration. Returns the new supergroup id in the resulting updates.

Transfer creator rights to another user. Requires the account 2FA password (Telegram enforces this).

Generate a new invite link with optional expiry, usage cap, and join-request gate.

List all invite links the current user can see in a chat.

Permanently revoke a previously generated invite link.

List users that joined a chat through a specific invite link.

List topics in a supergroup with forum mode enabled.

Create a new topic in a forum-enabled supergroup.

Rename / re-icon / close / hide a topic.

Save a draft for a dialog. Pass empty `text` to clear it.

Equivalent to `save_draft` with an empty text.

Return all dialog drafts the user has across chats.

Mute a chat. Without `untilDate`, mutes forever.

Clear a mute on a chat.

Return notification settings for a peer.

Update notify settings for a peer (sound, show preview, mute, story mute).

Create a new dialog folder (chat filter). `id` is auto-assigned to the next free slot 2..255.

Replace the rules of an existing folder. `id` is required.

Remove a folder by id.

Set the display order of folders by passing the list of ids in the desired sequence.

List all users in the contact book.

Add a user to your contacts.

Remove one or more users from the contact book.

Search users/chats/channels by a query (matches name, username, and indexed text).

Block a user from contacting you.

Lift a previous block.

List users currently on the block list.

Return current rules for one privacy key.

Replace the privacy rules for a key. `mode` chooses the base policy; `allowUsers`/`disallowUsers` add user-id exceptions.

Return the user's installed sticker sets.

Install a sticker set by its short name (e.g. "AnimatedEmojies").

Pin a sticker to the recently used list. Use `unsave: true` to remove it.

Return the current boost slots the user has available across channels.

Apply one or more boost slots to a channel.

Run an inline bot query (the `@bot query` form) and return the results.

Call any Telegram API method by its qualified name (e.g. `messages.SendMessage`, `channels.GetFullChannel`, `stories.GetAllStories`). String values for fields named peer/channel/user/fromPeer/toPeer/bot/chat are auto-resolved to InputPeer/InputUser. Use this only when no dedicated tool fits — the API surface is huge and there are no per-method safety checks.