Connection + authorization status, and the logged-in account summary. Secrets are never returned.

Full profile of the authorized account (id, names, username, phone, premium).

Complete User object for one account (all non-secret fields Telegram exposes). Defaults to the authorized account; pass user to look at somebody else. Phone numbers of other people are only present when their privacy settings share them.

Change first/last name and/or bio of the authorized account.

List the profile photos of a user (or of 'me'). Returns photo ids with their sizes and a downloadable file reference; use telegram_download_media only for chat messages, not for these.

Upload a local image as your own profile photo, or remove the current one with remove=true. Telegram also keeps the previous photo in your photo list; this does not delete it.

List the groups and channels this account has in common with another user.

Begin authorization when no session exists. Sends the login code to the user's Telegram app. Pass phone in international format (+15551234567) unless TELEGRAM_PHONE is set in the environment. After calling this, ask the user to read the code Telegram just sent them and call telegram_login_code. NEVER ask the user to paste the code anywhere except this chat, and never repeat it back.

Finish login by submitting the code Telegram sent the user. Call telegram_login_start first. If the account has 2FA, this returns needsPassword:true and you must ask the user for their 2FA password, then call telegram_login_password. Never echo the code or password back.

Complete login when the account has two-step verification enabled. Only call after telegram_login_code returned passwordRequired:true. The password is used once and never stored.

Abandon an in-progress login. No code or password is retained after this.

Read-only health check: config, installed version, state dir, session presence, session file permissions (auto-repaired to 0600), and live authorization. Returns { healthy, checks[], account }. A missing or unauthorized session is reported as a failed check, not an error — call telegram_login_start to fix it. An available update is informational and never fails the check. Never returns the api_hash or the session string.

Create or update the .env file this server loads: TELEGRAM_API_ID, TELEGRAM_API_HASH, optional TELEGRAM_PHONE, and TELEGRAM_ALLOW_ALL_CHATS. Get api_id/api_hash from https://my.telegram.org/apps. Never call this with a hash the user pasted in chat unless they asked you to; the hash is written to disk and never returned. Existing other keys in .env are preserved. The MCP server must be restarted to pick up new values.

List dialogs (DMs, groups, channels). Set includeAll=false to only return allowlisted chats when a policy is configured. Default returns everything the account can see.

Fetch detailed info for a chat/user/channel: title, username, id, type, member count, description.

List participants of a group/channel (if permitted). Returns id, name, username, role.

Join a public channel/group by @username or invite link.

Leave a group/channel by id or @username.

Permanently delete a group or channel this account owns, including its history. This is the counterpart of telegram_create_group / telegram_create_channel, and is stronger than telegram_leave_chat: the chat stops existing for everyone, not just for this account. Only the creator can delete; Telegram refuses otherwise.

Mute a chat for N days (0 = unmute). Uses default mute behaviour when days>0.

Change a group/channel title and/or description. Needs admin rights; Telegram refuses otherwise. Omit a field to leave it untouched. Titles are 1-128 chars, about is up to 255.

Get a chat's invite link, or revoke it (which kills the old link). Needs admin rights. revoke=true returns the newly issued link, so the chat stays joinable.

Pin or unpin a chat in your own dialog list (not a message — use telegram_pin_message for that). Local to the account: nothing changes for other members.

Move a chat into the Archived folder or back to the main list. Local to the account. Folder id 0 means 'not archived'; 1 is the default archive folder.

Delete messages from a chat. Defaults to your own copy only (revoke=false). revoke=true also removes them for everyone, which needs the rights to do so. Returns the message count Telegram reports as affected when it says.

Read recent messages from a chat. chat = @username, numeric id, or 'me'. Newest-first, max 100. The answer carries hasMore and nextOffsetId: pass that id back as offsetId to page further back. A page shorter than limit with hasMore:false means the history is exhausted.

Full-text search within a chat. Returns matching messages newest-first (max 100 per page). The answer carries hasMore and nextOffsetId for paging deeper into the matches.

Fetch one message by id from a chat.

Send a text message to a chat. Supports replyTo and topicId. Returns the new message id and sent:true. Full access: sends immediately.

Edit one of your own messages in a chat by message id.

Delete one or more messages in a chat by id. revoke=true deletes for everyone (your messages).

Forward messages by id from one chat to another.

Send a reaction (emoji) to a specific message. Pass emoji 'none' or '' to clear reactions.

Pin or unpin a message in a chat.

Mark all messages in a chat as read.

Show 'typing…' in a chat for a few seconds, or clear it. Telegram expires the indicator on its own; pass action 'cancel' to remove it immediately. Nothing is sent to the chat history.

Remove all pinned messages from a chat in one call.

Dump a chat's message history to a JSON file in the export directory and return the path. Useful for archiving or handing a full conversation to another tool. Newest-first, max 1000.

Build the t.me link for one message, or for a whole chat when messageId is omitted. Works for public and private chats — a private chat yields the /c/ form, which needs no username.

Send a poll. 2-10 answers. multipleChoice lets voters pick several; quiz makes it a quiz (a correct answer index is required, 0-based). anonymous=false shows who voted.

Send a phone contact (vCard) into a chat. Nothing is saved to your contacts list.

Read the messages currently pinned in a chat, with sender and text.

Full-text search over all chats at once (not one chat). Returns matches with the chat they belong to, newest first. Optional minDate/maxDate (unix seconds) narrow the window. Note: Telegram's own cursor can repeat rows between pages; that overlap is removed for you and reported as skippedRepeat.

Download the attachment of a message to the local media directory. Returns local path + size. Set TELEGRAM_MAX_DOWNLOAD_BYTES in env for a cap (0 = unlimited).

Remove one record from the local downloads index by its id, optionally deleting the file it points at. This is local bookkeeping only — nothing is deleted on Telegram. Use it to prune records whose file is already gone (telegram_list_downloads reports exists:false for those).

Send a local file as a document (forceDocument) or auto-detected media. Supports caption. Sends immediately.

Send a local image as a photo (inline preview). Sends immediately.

List files downloaded by this server (paths, sizes, source message).

Send a geographic point to a chat. lat/long are decimal degrees; optional accuracy in metres. Sends immediately.

Global search for users/chats by name or @username. Returns ids, usernames, types.

List saved contacts (id, name, username, phone).

Save a Telegram user as a contact by @username or user id.

Remove saved contacts by @username, user id, or numeric id. This is the inverse of telegram_add_contact and may remove several at once. The account stays subscribed to nothing new — it only forgets the saved contact entry.

Create a new group chat with the given users (by @username or id) and a title.

Create a broadcast channel with the given title and optional description.

Block or unblock a user. A blocked user cannot message you or see your profile. Pass unblock=true to reverse it.

List the users this account has blocked (id, name, username, blocked-at).

Read this server's own call log, newest first. Every tool call is appended with timestamp, tool name, sanitized args and outcome; secrets are redacted at write time. Optional filters: tool name and outcome ('ok' | 'error'). Purely local — nothing is read from Telegram.

Counts per tool and per outcome from the local audit log, plus the first and last recorded call. Use it to see what an agent has actually done to the account, without paging through entries.

List every device currently logged into this account, marking the one running this server with current:true. Each entry carries the hash that telegram_logout_session needs.

Revoke one session by the hash reported by telegram_list_sessions. Pass all=true to revoke every session except this one. Refuses to revoke the session running this server.

Invite one or more users into a group/channel this account administers. Users are resolved from @username or id. Returns the ids Telegram reports as invited, plus the ones it refused.

Grant or revoke admin rights for a member. preset: 'moderator' (default, can delete and ban), 'full' (everything except anonymous), 'none' (demote). Optional custom title (rank).

Remove a member from a group or channel. kick=true bans them (default), unban=true lifts the ban so they may rejoin. Nothing is deleted from the chat history.

Upload a local image as the group/channel photo, or remove the photo with remove=true. Needs admin rights. The file is read from disk, never from a URL.

List the admins of a group or channel with the rights each one holds and their custom rank. Uses the dedicated admin filter, so it does not page through every member.

List the messages queued to be sent later in a chat, with their planned send time. Scheduling is done by the client; this reads back what is already queued.

List the account's chat folders, with the peers each one includes and excludes. A folder with no explicit peers is rule-based (e.g. all non-contacts).

Translate text using Telegram's own translation service. Pass chat+messageId to translate an existing message, or text to translate a literal string. targetLang is an ISO code such as 'id' or 'en'.