telegram-mcp

List all configured Telegram accounts with profile info.

Promote a user to admin in a group/channel.

Demote a user from admin in a group/channel.

Set granular admin rights for a user in a supergroup or channel.

Get all admins in a group or channel.

List a message's inline ("glass") buttons with the index needed to press one.

Press one inline ("glass") button, chosen by its index from inspect_buttons.

Ask Telegram whether a public username is free for this channel.

Change a channel's public username — or, with an empty one, make it private.

The statistics Telegram keeps for a channel, a supergroup, or one post.

The channels Telegram recommends as similar to this one.

Attach a discussion group to a channel, or detach the one it has.

Require members to join a supergroup before they can post in it.

Require admin approval before someone joins.

Hide messages sent before a member joined.

Hide the member list from non-admins.

Sign channel posts with the name of the admin who sent them.

Show a forum as one flat message list rather than as topics.

Subscribe (join) to a public channel or supergroup by username or ID.

Mute notifications for a chat.

Unmute notifications for a chat.

Archive a chat.

Unarchive a chat.

Get a paginated list of chats. Args: page: Page number (1-indexed). Paging stops at 100,000 chats in. page_size: Number of chats per page (1-200; a larger value is served as 200 and the reply reports both numbers).

List available chats with metadata.

Get detailed information about a specific chat.

Search chats, channels and bots by username or title.

Resolve a username to a user or chat ID.

Get full info of a channel or group including description/about text.

List chats shared with a specific user.

List user IDs who have read a specific message.

Export a t.me/... link for a specific message.

Remember what the user calls someone, so any tool taking a chat_id understands it.

List remembered contacts, one row per person with all of their aliases.

Forget one remembered alias. Exact match only — deleting the wrong memory is silent, so fuzzy matching is deliberately not used here. Use list_contact_aliases first if unsure of the exact wording.

List all contacts in your Telegram account.

Search for contacts by name, username, or phone number using Telethon's SearchRequest. Saved favorite aliases matching the query are checked first and returned at the top. Args: query: The search term to look for in contact names, usernames, or phone numbers.

Get all contact IDs in your Telegram account.

Find a direct chat with a specific contact by name, username, or phone.

List all chats involving a specific contact.

Get the most recent message with a contact.

Add a new contact to your Telegram account. Args: phone: The phone number of the contact (with country code). Required if username is not provided. first_name: The contact's first name. last_name: The contact's last name (optional). username: The Telegram username (without @). Use this for adding co…

Delete a contact by user ID. Args: user_id: The Telegram user ID or username of the contact to delete.

Block a user by user ID. Args: user_id: The Telegram user ID or username to block.

Unblock a user by user ID. Args: user_id: The Telegram user ID or username to unblock.

Import a list of contacts. Each contact should be a dict with phone, first_name, last_name.

Export all contacts as a JSON string.

Get a list of blocked users.

Send a contact to a chat. Args: chat_id: The chat ID or username. phone_number: Contact's phone number. first_name: Contact's first name. last_name: Contact's last name (optional). vcard: Additional vCard data (optional).

Every premium/custom emoji in a message, with the id needed to replace one.

Swap the premium emoji in a message for a different one, keeping everything else.

Report whether the file tools are usable, and exactly what to configure if not.

List the message effects this account can send, so one can be CHOSEN.

Resolve a message-level effect ID to its real assets, and optionally show one.

Find the self-destructing media in a chat, before it is opened.

Send a photo, video or voice message that destroys itself after viewing.

Block until a new incoming private message from a non-bot user arrives, then return immediately with the list of chats that currently have pending (unprocessed) incoming messages. If nothing arrives within `timeout` seconds, returns {"event": false, "reason": "timeout"}. Lets the agent react to even…

Event-driven, DEBOUNCED wait. Blocks until some private user chat has received one or more incoming messages AND then gone quiet for `settle_ms` — so a client who types several messages (or sends file + text) in a row is delivered as ONE settled burst instead of waking the agent on every message. Re…

CLAUDE CODE ONLY. Enable callback mode: a background task appends every settled incoming burst as one JSON line to the feed file, so an external watcher can wake the agent per event instead of the agent blocking in wait_for_settled_message.

Disable the incoming event feed (stops writing to the feed file).

Report whether the incoming event feed is enabled, its file path, and the watch command for waking an agent per event.

Get all dialog folders (filters) with their IDs, names, and emoji. Returns a list of folders that can be used with other folder tools.

Get detailed information about a specific folder including all included chats.

Create a new dialog folder.

Add a chat to an existing folder.

Remove a chat from a folder.

Delete a folder. Chats in the folder are preserved, only the folder is removed.

Change the order of folders in the folder list.

Create a new group or supergroup and add users.

Create a channel or supergroup, private by default or public under a username.

Edit the title of a chat, group, or channel.

Edit the photo of a chat, group, or channel. Requires a file path to an image.

Edit the description ("About") of a chat, group, or channel.

Delete the photo of a chat, group, or channel.

Enable or disable slow mode for a supergroup.

Leave a group or channel by chat ID.

List participants in a group or channel with pagination. Args: chat_id: The group or channel ID or username. page: Page number (1-indexed, default 1). Paging stops at 100,000 participants in. page_size: Number of participants per page (default 200, max 1000; a larger value is served as 1000).

Invite users to a group or channel.

Full API view of one message, optionally with a picture of it.

Full API view of the newest messages in a chat.

Mint an additional invite link, with any conditions Telegram supports.

Change the conditions on an existing invite link.

Stop an invite link working. Anyone holding it is locked out.

The invite links this account created for a chat, with their conditions.

People waiting for approval to join, from links that require it.

Let someone in, or turn them away, from the pending-approval queue.

Read the invite link a group or channel already has.

Mint a NEW primary invite link for a chat, replacing the previous one.

Join a chat by its invite hash (the part after t.me/+ or t.me/joinchat/).

Join a chat by invite link.

Read one admin's rights through TDLib, which sees the ones Telethon cannot.

Switch ONE admin right on or off, including the ones Telethon cannot deliver.

Send a file to a chat. Args: chat_id: The chat ID or username. file_path: Absolute or relative path to the file under allowed roots. Pass a list of 2-10 paths to send them as one Telegram media group. caption: Optional caption for the file or media group. topic_id: Optional forum topic ID (from list…

Send multiple photos/videos as one Telegram media group (album).

Download media from a message in a chat.

Send a voice message to a chat. File must be an OGG/OPUS voice note.

Upload a local file to Telegram and return upload metadata.

Get info about media in a message.

List this account's packs, with the identifiers other tools need.

Send a sticker to a chat. File must be a valid .webp sticker file.