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 /root/.telegram-agent/downloads (override with MCP_TELEGRAM_DOWNLOADS env). Returns the absolute path.

Download the profile photo of a user/chat/channel. Saved under /root/.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.