tdl-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| TDL_NS | No | tdl namespace, passed as -n <ns> on every call. Use it to keep separate Telegram accounts/sessions apart. | |
| TDL_BIN | No | Path to the tdl binary. Default: 'tdl' on PATH, falling back to /opt/homebrew/bin/tdl |
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 |
|---|---|
| tg_statusA | Check whether the local tdl Telegram session is logged in and usable. Call this first if another tg_* tool fails or before starting Telegram work. Never errors — returns {logged_in:false, hint} when the session is missing. |
| tg_chatsA | List the Telegram dialogs (chats/channels/groups/users) visible to the logged-in session, as [{id, type, name, username}]. Use it to find the chat id or @username to pass as |
| tg_messagesA | Export recent media messages from one chat (by id or @username) and return them as compact {id, date, file, text} objects — newest range exported via tdl. Use last_n for 'the last N media messages', or since_id to fetch only messages after a known message id (incremental reads). Read-only. |
| tg_downloadA | Download media files from one chat (by id or @username) to a local directory and return the absolute paths of newly downloaded files. Use extensions (csv, e.g. 'xlsx,pdf') to fetch only certain file types; since_id for 'everything new after message X'; last_n for 'the latest N media messages' (default 100). Already-present files are skipped (--skip-same). |
| tg_download_urlA | Download the media of specific Telegram messages given their t.me links (e.g. https://t.me/channel/123) and return the absolute paths of newly downloaded files. Use when you already have message links rather than a chat to scan. Already-present files are skipped (--skip-same). |
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 5 tools
Each tool has a clearly distinct purpose: listing chats, downloading media by chat, downloading media by URL, exporting message metadata, and checking session status. The two download tools are differentiated by source (chat vs. message links), and tg_messages returns metadata, not files, avoiding overlap.
All tools share the 'tg_' prefix, but the naming pattern is inconsistent: some use nouns (tg_chats, tg_messages, tg_status) and others use verbs (tg_download, tg_download_url). This mix could be confusing; a consistent verb_noun pattern would improve predictability.
With 5 tools, the server covers the core functionality of a Telegram media downloader (chat discovery, message inspection, two download methods, and status check) without unnecessary duplication or missing essentials.
The tool surface covers the main workflow: find chats, list messages, download media, and verify session. Minor gaps exist, such as the lack of date-range filtering or a direct login/logout tool, but these are not critical for common use cases.