codex-telegram
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| TG_FILES_DIR | No | Absolute path to the files directory. | |
| TG_CONFIG_DIR | No | Set to use another directory for configuration state. Defaults to %LOCALAPPDATA%\codex-telegram on Windows and ~/.local/state/codex-telegram on macOS/Linux. | |
| TG_USE_DOTENV | No | Set to '1' to opt in to loading .env for local development only. Prevents a cloned repository from silently becoming the location of a Telegram session. | |
| TG_CONFIG_FILE | No | Absolute path to the configuration file. | |
| TG_DATABASE_DIR | No | Absolute path to the TDLib database directory. | |
| TG_DOWNLOADS_DIR | No | Absolute path to the downloads directory. Explicit downloads are saved here. | |
| TG_MAX_DOWNLOAD_BYTES | No | Maximum download size in bytes. Default is 100 MiB. Set to a positive byte value to change the cap. |
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_get_meA | Get the authenticated personal Telegram account. The phone number is intentionally omitted for privacy. |
| telegram_healthA | Diagnose local Telegram plugin setup without exposing credentials or message data. Optionally verifies the saved TDLib session. |
| telegram_list_chatsA | List recent Telegram chats, groups, channels, and Saved Messages. Use search when the user names a person or a chat. |
| telegram_get_chatA | Get details for one Telegram chat by its exact chat_id. For a private chat, returns the other person's Telegram user_id and profile fields when Telegram makes them available. |
| telegram_get_pinned_messageA | Read the currently pinned message in a known Telegram chat. Returns text and metadata only. |
| telegram_search_chatsA | Find people, groups, channels, or Saved Messages by name, username, or title. Private-chat results include the contact's Telegram user_id where available. Before sending to an ambiguous name, search and confirm the intended chat. |
| telegram_resolve_chatA | Resolve a person, group, channel, or @username into candidate chat IDs for later read tools. This never sends a message. |
| telegram_get_messagesA | Read up to 100 messages in a known Telegram chat. The tool keeps requesting TDLib history internally when TDLib returns a partial page. Returns text and metadata only; media is not downloaded automatically. |
| telegram_search_messagesA | Search Telegram message text globally, or inside a supplied chat_id. Use this to locate a topic, deadline, specification, or file discussion. |
| telegram_search_mediaA | Find recent photos, videos, documents, audio, voice notes, animations, or URL messages inside one known chat. Returns message metadata only; no media is downloaded automatically. |
| telegram_get_unreadA | List recent Telegram chats that have unread messages. |
| telegram_get_inline_buttonsA | List the inline buttons attached to one Telegram message. Use row and column values from this result with telegram_click_inline_button. |
| telegram_click_inline_buttonA | Press a Telegram bot inline callback button by row and column. This sends a callback query and may change bot state. Callback buttons only; payments, URL/login, web-app, game, and password buttons are blocked. |
| telegram_react_to_messageA | Add or remove your emoji reaction on one Telegram message. This changes external state: use only after the user explicitly confirms the chat, message, emoji, and whether it should be added or removed. |
| telegram_edit_own_messageA | Edit one text message previously sent by the authenticated Telegram account. This changes external state: require explicit confirmation of the chat, message, and replacement text. |
| telegram_delete_own_messageA | Delete one message previously sent by the authenticated Telegram account, revoking it for everyone when Telegram permits. This is destructive and requires explicit confirmation. |
| telegram_send_messageA | Send text through the personal Telegram account. This changes external state: call only after the user has explicitly confirmed both recipient chat and exact message. |
| telegram_reply_messageA | Reply to a specific Telegram message. This changes external state: call only after user confirmation of recipient and text. |
| telegram_send_fileA | Send a local file through the personal Telegram account. This changes external state: call only after the user explicitly confirms recipient, file, and caption. |
| telegram_download_fileA | Download media attached to one Telegram message. destination, when supplied, must be a new file name only; it is saved inside the configured Telegram downloads directory and never overwrites an existing file. |
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 20 tools
Most tools target distinct actions, but several discovery tools overlap: telegram_search_chats and telegram_resolve_chat both find chats by name and return candidate IDs, and telegram_list_chats vs telegram_get_unread both list recent chats. Descriptions are clear enough for an attentive agent, but boundary confusion is likely.
All tools share a telegram_ prefix and nearly all follow verb_noun naming like list_chats, send_message, and download_file. Minor deviations such as telegram_health, telegram_get_me, and telegram_get_unread break the pattern slightly but do not create serious confusion.
Twenty tools is on the heavy side, especially with several discovery tools that could plausibly be merged without losing capability. Each tool does represent a legitimate Telegram operation, so the count is defensible but feels somewhat bloated.
The server covers chat discovery, reading and searching messages, sending/reply, editing/deleting own messages, reactions, inline buttons, and media download. Missing capabilities like marking chats read, forwarding messages, or sending non-file media are minor gaps for a personal-assistant workflow and can be worked around.