Telegram MCP Server
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| DATA_DIR | No | The directory where downloaded chat data and media files will be stored. | |
| TELEGRAM_API_ID | Yes | The API ID for your Telegram application, obtained from my.telegram.org. | |
| TELEGRAM_API_HASH | Yes | The API hash for your Telegram application, obtained from my.telegram.org. | |
| TELEGRAM_SESSION_PATH | No | The file path where the telegram.session file is located or should be saved. |
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
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| telegram_list_chatsA | List your Telegram dialogs (chats, groups, channels). Returns chat ID, title, type, and username. Use this to find the chat_id needed for other tools. |
| telegram_find_chatA | Search for a specific chat by name, username, or ID. Returns the matching chat info or null if not found. |
| telegram_get_historyA | Fetch messages from a Telegram chat. Returns message text, sender, date, and media info. Does NOT download media files — use telegram_sync_chat for that. Useful for previewing chat contents before a full sync. |
| telegram_sync_chatA | Full sync: downloads all messages and media files from a chat to local storage. Supports incremental sync — on subsequent runs, only fetches new messages. Files are saved to data/raw/{chat_id}/. This is the main tool for extracting chat data including photos and documents. Use since_date to limit the sync range, or omit for full/incremental sync. |
| telegram_download_mediaA | Download media from a specific message. Use this for targeted downloads instead of a full sync. Returns file path and metadata. |
| telegram_sync_statusA | Check the sync status for a chat: last sync date, total synced messages, last message ID. Useful before deciding whether to run a new sync. |
| telegram_list_mediaA | List all media files that have been downloaded for a chat. Requires a previous telegram_sync_chat run. Filter by type: photo, document, video, voice, or all. |
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 7 tools
Each tool has a clearly distinct purpose with no overlap: download_media, find_chat, get_history, list_chats, list_media, sync_chat, and sync_status all target specific operations in the Telegram data extraction workflow. The descriptions explicitly differentiate tools like get_history (preview without downloads) versus sync_chat (full sync with downloads), preventing misselection.
All tools follow a consistent 'telegram_verb_noun' pattern throughout, using snake_case and clear action verbs (download, find, get, list, sync). This predictable naming makes the tool set easy to navigate and understand at a glance.
With 7 tools, this server is well-scoped for its purpose of Telegram data extraction and management. Each tool earns its place by covering distinct aspects like discovery (list_chats, find_chat), preview (get_history), full sync (sync_chat), media handling (download_media, list_media), and status checking (sync_status).
The tool surface provides complete coverage for the Telegram data extraction domain: it supports chat discovery, message history retrieval, full sync with incremental updates, media download and listing, and status monitoring. There are no obvious gaps—agents can perform end-to-end workflows from finding chats to extracting and managing their data.