telegram-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| TELEGRAM_API_ID | Yes | Your Telegram API ID from my.telegram.org | |
| TELEGRAM_API_HASH | Yes | Your Telegram API hash from my.telegram.org |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| prompts | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| whoamiA | Show which Telegram account this server is signed in as. |
| list_chatsA | List recent dialogs, newest first. Use the returned chat_id for every other tool. |
| search_chatsA | Find dialogs by title or username. Matches across scripts, so "Вадим" finds "Vadim" and "Sasha" finds "Саша". Several chats often match a common first name — check the results and pick the right chat_id before sending anything. |
| search_public_chatsA | Search all of Telegram — not the user's own dialogs — for public channels, groups, bots and users by name or @username. Use this to find a chat the user has never opened; use search_chats for the ones they already have. Results are split into "mine" (their own contacts and dialogs) and "public" (everyone else). Public results are strangers: several channels share one name, and the flags say which is verified and which is flagged as a scam. |
| search_public_postsA | Full-text search over posts in every public channel on Telegram, whether or not the user follows them. This is the whole network, not the account: use search_messages for the user's own chats. Telegram rations these searches — the result reports how many free ones are left today, so do not spend them on repeated near-identical queries. |
| get_historyA | Read the most recent messages of a chat, newest first. Read-only: this does not mark anything as read. |
| search_messagesA | Full-text search over messages, inside one chat or across the whole account when chat is omitted. |
| send_messageA | Send a text message. It is delivered immediately and there is no undo — confirm the chat_id came from list_chats or search_chats first. |
| send_fileA | Upload a local file to a chat. Delivered immediately, no undo. |
| download_mediaB | Download the media attached to one message. Returns the saved path. |
| list_contactsA | List saved contacts. |
| mark_readA | Mark a chat as read. The other side sees read receipts — this is visible to them. |
| sample_my_messagesA | Collect messages the user themselves wrote, as raw material for describing how they write. Private chats only, text only, no recipients — this is a style sample, not a transcript. |
| save_style_profileA | Store the description of how the user writes. Replaces any previous one. It is loaded on every start and used when drafting on their behalf. |
| get_style_profileA | Show the stored writing-style profile, if there is one. |
| forget_style_profileA | Delete the stored writing-style profile. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| personalize | Read messages I have sent, describe how I write, and save it locally at /root/.telegram-mcp/style.md for drafting later. |
| draft_reply | Write a reply using the saved style profile. Shows it, never sends. |
| catch_up | Go through unread dialogs and report what needs an answer. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 16 tools
Each tool has a distinct purpose: account identity, chat listing/searching by scope, messaging, file/media operations, read status, and style profiling. No two tools overlap in function; searching is divided by scope (own chats, public channels, public posts) to avoid ambiguity.
Most tools follow verb_noun snake_case pattern (list_chats, search_messages, send_file). 'whoami' is a minor deviation as a single word command. Overall consistent and predictable.
With 16 tools, the set covers the core Telegram operations without being overly large. The count is slightly above the typical 3-15 range but still well-scoped for a messaging server that includes a style profiling subsystem.
The tool surface covers listing, searching, sending, reading, and style profiling. However, common CRUD operations like message editing, deletion, reactions, and chat management (create/leave/mute) are missing, which agents might need.