telegram-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| TELEGRAM_API_ID | No | Your Telegram API ID (advanced, overrides broker) | |
| TELEGRAM_API_HASH | No | Your Telegram API hash (advanced, overrides broker) |
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
} |
| logging | {} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
| extensions | {
"io.modelcontextprotocol/ui": {}
} |
| experimental | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| digest_unreadA | KILLER-тул: дайджест непрочитанного. T9: iter_dialogs → топ-N чатов с unread_count>0 → подтянуть per_chat последних сообщений. Чтение НЕ помечает прочитанным (mark_read не зовём). Ограничивать (FloodWait). read-only. Выбор топа: сортируем чаты по unread_count по убыванию — наверх всплывает самый большой бэклог (что больше всего пропустил). Сообщения внутри чата — newest-first (как отдаёт iter_messages), не помечаем прочитанным. |
| download_mediaA | Скачать вложение из конкретного сообщения на диск (локально). T11: get_messages(entity, ids=message_id) → message.download_media(dest). Точечно, не «все фото». read-only (download_*). |
| find_chatA | Найти чат ПОИСКОМ (не перебором диалогов): серверный contacts.Search. contacts.SearchRequest отдаёт РАНЖИРОВАННЫЕ совпадения в my_results (свои контакты/чаты — релевантнее) и results (глобальные публичные); users/chats — лишь пул сущностей для резолва. Берём именно my_results→results, а НЕ весь пул (иначе глобальный шум). Fallback на локальный фильтр диалогов — TODO, только если тест покажет дыру по приватным группам (docs/decisions.md). read-only. |
| get_historyA | Последние сообщения чата (chat = id/username/ссылка/название → resolve). T6: iter_messages(entity, limit) → {id, date, sender, text}. read-only. |
| list_chatsB | Список диалогов с непрочитанным: title, type, unread_count, последнее сообщение. T5: iter_dialogs(limit, archived) → chat_brief(...). read-only. |
| get_meA | Текущий аккаунт: id, имя, username. T12: get_me(). read-only. |
| get_participantsC | Участники чата/группы. T12: iter_participants(entity, limit). read-only. |
| get_pinnedB | Закреплённые сообщения чата. T12: get_pinned / iter_messages(pinned). read-only. |
| resolve_chatA | Точный resolve чата/юзера по username/ссылке/id/точному имени. T10: resolve_entity(ref) → chat_brief. read-only. Если не найдено — исключение Telethon (ValueError/UsernameNotOccupiedError и т.п.) пробрасывается наверх, оунер обрабатывает его на интеграции. |
| search_in_chatA | Поиск сообщений ВНУТРИ чата по тексту. T7: iter_messages(entity, search=query, limit). read-only. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 10 tools
Each tool targets a specific Telegram resource and action: account info, unread digest, media download, chat search, message history, chat list, participants, pinned messages, entity resolution, and in-chat search. Potential overlaps (e.g., find_chat vs resolve_chat) are differentiated by search vs exact match, and get_history vs search_in_chat by unfiltered retrieval vs text query.
All tool names follow a consistent verb_noun snake_case pattern (get_me, digest_unread, download_media, find_chat, get_history, list_chats, get_participants, get_pinned, resolve_chat, search_in_chat). The verbs are varied but appropriate to each action, and there are no style mixes or camelCase deviations.
With 10 tools, the set is well-scoped for a Telegram read-only/digest MCP server. Each tool covers a distinct need without unnecessary redundancy, and the count is within the ideal 3-15 range.
The server covers the core read-only workflow: account info, listing chats, unread digests, history, search, media download, participants, pinned messages, and entity resolution. Minor gaps exist, such as no direct tool for getting a single message by ID or detailed user/chat profiles, but these are easily worked around with existing tools.