Telegram MCP Server
by jkotasjkotas
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| MCP_HOST | No | Host to bind for http/sse transports. Default is 127.0.0.1. | |
| MCP_PORT | No | Port to bind for http/sse transports. Default is 8765. | |
| GROQ_API_KEY | No | Groq API key required when using the groq transcription engine. | |
| MCP_TRANSPORT | No | MCP transport: 'stdio' (default), 'http', or 'sse'. | |
| TELEGRAM_API_ID | Yes | Telegram API ID from my.telegram.org/apps. | |
| MCP_ALLOWED_HOSTS | No | Comma-separated Host headers accepted for http/sse, e.g. mcp.example.com. Supports a :* suffix for any port. | |
| TELEGRAM_API_HASH | Yes | Telegram API hash from my.telegram.org/apps. | |
| TELEGRAM_AUDIT_LOG | No | Path for the append-only deletion audit log. Default is telegram_audit.log next to the server. | |
| TELEGRAM_FLOODGATE | No | Set to 0 to disable the local flood-prevention gate. Enabled by default. | |
| TELEGRAM_LANG_CODE | No | Telegram client language code. | |
| MCP_ALLOWED_ORIGINS | No | Comma-separated browser origins allowed to call the http/sse server. Supports a :* suffix for any port. | |
| TELEGRAM_EVENT_FEED | No | Set to 1 to auto-enable the incoming event feed. | |
| TELEGRAM_PROXY_HOST | No | Proxy hostname. Per-account overrides use TELEGRAM_PROXY_HOST_<LABEL>. | |
| TELEGRAM_PROXY_PORT | No | Proxy port. Per-account overrides use TELEGRAM_PROXY_PORT_<LABEL>. | |
| TELEGRAM_PROXY_RDNS | No | Whether to use remote DNS for SOCKS proxies, e.g. true. | |
| TELEGRAM_PROXY_TYPE | No | Proxy type: 'socks5', 'socks4', 'http', or 'mtproxy'. Per-account overrides use TELEGRAM_PROXY_TYPE_<LABEL>. | |
| TELEGRAM_TRANSCRIBE | No | Voice transcription mode: 'off', 'on-demand' (default), or 'auto'. | |
| TELEGRAM_APP_VERSION | No | App version shown in Telegram active sessions. | |
| TELEGRAM_ALIASES_FILE | No | Override the path for the contact aliases store. | |
| TELEGRAM_DEVICE_MODEL | No | Device model shown in Telegram active sessions. | |
| TELEGRAM_PROXY_SECRET | No | MTProxy secret when TELEGRAM_PROXY_TYPE=mtproxy. Per-account overrides use TELEGRAM_PROXY_SECRET_<LABEL>. | |
| TELEGRAM_SESSION_LOCK | No | Session lock mode. Set to 'shared' to allow multiple instances on one host to share the same session. | |
| TELEGRAM_SESSION_NAME | No | Path/name for a persistent SQLite Telegram session file. For multi-account setups, use a suffixed variable such as TELEGRAM_SESSION_NAME_<LABEL>. | |
| TELEGRAM_ALLOWED_ROOTS | No | Semicolon-, comma-, or colon-separated allowed filesystem roots for file/media tools. | |
| TELEGRAM_CONTACT_FUZZY | No | Set to 0 to disable fuzzy contact-name suggestions. | |
| TELEGRAM_EXPOSED_TOOLS | No | Tool-surface restriction: 'all' (default), 'read-only', or 'read-only+<tool>,<tool>', optionally followed by '-<tool>,<tool>'. | |
| TELEGRAM_EVENT_LOG_SIZE | No | Maximum number of per-message events kept in memory. Default is 2000; 0 disables the log. | |
| TELEGRAM_MEDIA_BASE_URL | No | Base URL clients reach for signed media download/upload URLs, e.g. https://tg.example.com. | |
| TELEGRAM_PROXY_PASSWORD | No | Optional proxy password. Per-account overrides use TELEGRAM_PROXY_PASSWORD_<LABEL>. | |
| TELEGRAM_PROXY_USERNAME | No | Optional proxy username. Per-account overrides use TELEGRAM_PROXY_USERNAME_<LABEL>. | |
| TELEGRAM_SESSION_STRING | No | Telegram session string. For multi-account setups, use a suffixed variable such as TELEGRAM_SESSION_STRING_<LABEL>. | |
| TELEGRAM_SYSTEM_VERSION | No | System version shown in Telegram active sessions. | |
| TELEGRAM_DOWNLOAD_SUBDIR | No | Subdirectory under the first allowed root for downloaded media. Default is downloads. | |
| TELEGRAM_EVENT_FEED_FILE | No | Override the incoming event feed JSONL path. | |
| TELEGRAM_FILE_EXTENSIONS | No | Semicolon-separated tool allowlists in the form tool:.ext,.ext, e.g. send_file:.pdf,.png;upload_file:.pdf,.png. | |
| TELEGRAM_SESSION_STRINGS | No | Whitespace-, comma-, or semicolon-separated list of interchangeable session strings for a per-account session pool. | |
| TELEGRAM_ALLOWED_CHAT_IDS | No | Comma-separated allowed chat IDs or usernames. Forum topics can be restricted with <chat>:<topic id>. | |
| TELEGRAM_BLOCKED_CHAT_IDS | No | Comma-separated marked chat IDs or usernames to block across all accounts. | |
| TELEGRAM_SYSTEM_LANG_CODE | No | Telegram system language code. | |
| TELEGRAM_CATCH_UP_INTERVAL | No | Seconds between catch-up requests for missed updates. Minimum is 30; default 0 means off. | |
| TELEGRAM_EXPECTED_USERNAME | No | Expected Telegram username for the account. Per-account checks use TELEGRAM_EXPECTED_USERNAME_<LABEL>. | |
| TELEGRAM_SERVER_ROOTS_ONLY | No | Set to 1 to use configured server roots directly and skip roots/list. | |
| TELEGRAM_TRANSCRIBE_ENGINE | No | Default transcription engine: 'groq' (default), 'telegram', 'openai', or 'whisper'. | |
| TELEGRAM_LOCK_GRACE_SECONDS | No | Seconds a second process waits for an existing session lock before refusing to start. Default is 20. | |
| TELEGRAM_TRANSCRIBE_TIMEOUT | No | Timeout in seconds for a single HTTP transcription request. Default is 120. | |
| TELEGRAM_TRANSCRIBE_LANGUAGE | No | ISO-639-1 language hint passed to groq, openai, and whisper transcription engines. | |
| TELEGRAM_TOOL_TIMEOUT_SECONDS | No | Server-side ceiling in seconds for every tool call. Default is 55; 0 disables the ceiling. | |
| TELEGRAM_TRANSCRIPT_CACHE_DIR | No | Directory for the local SQLite transcript cache. Default is data/transcripts. | |
| TELEGRAM_FLOOD_SLEEP_THRESHOLD | No | Maximum seconds Telethon sleeps silently on FloodWait. Default is 60; 0 disables silent sleeping. | |
| TELEGRAM_ROOTS_TIMEOUT_SECONDS | No | Timeout in seconds for roots/list. Default is 10. | |
| TELEGRAM_TRANSCRIBE_MAX_VOICES | No | Maximum number of missing voice transcripts prefetched per listing call in auto mode. Default is 5. | |
| TELEGRAM_TRANSCRIBE_OPENAI_URL | No | API base URL for an OpenAI-compatible /audio/transcriptions endpoint. Required for the openai transcription engine. | |
| TELEGRAM_TRANSCRIBE_GROQ_MAX_MB | No | Maximum recording size in MB for the groq transcription engine. Default is 25. | |
| TELEGRAM_TRANSCRIBE_MAX_SECONDS | No | Maximum total seconds of audio prefetched per listing call in auto mode. Default is 300. | |
| TELEGRAM_TRANSCRIBE_OPENAI_MODEL | No | Model name for the OpenAI-compatible transcription endpoint. Default is whisper-1. | |
| TELEGRAM_RESOLVE_PHONE_STATE_FILE | No | Path to a file that keeps phone-lookup counts across restarts. | |
| TELEGRAM_TRANSCRIBE_OPENAI_MAX_MB | No | Maximum recording size in MB for the openai transcription engine. Default is 25. | |
| TELEGRAM_TRANSCRIBE_WHISPER_MODEL | No | Local faster-whisper model name. Default is small. | |
| TELEGRAM_RESOLVE_PHONE_MAX_PER_DAY | No | Maximum phone lookups per rolling 24 hours. 0 or unset means no cap. | |
| TELEGRAM_TRANSCRIBE_OPENAI_API_KEY | No | Bearer token for the OpenAI-compatible transcription endpoint. Optional for keyless local servers. | |
| TELEGRAM_TRANSCRIBE_WHISPER_DEVICE | No | Device for the whisper engine: 'auto', 'cpu', or 'cuda'. | |
| TELEGRAM_ALLOW_SERVER_ROOTS_FALLBACK | No | Set to 1 to fall back to server CLI roots when client MCP Roots are empty or fail. | |
| TELEGRAM_TRANSCRIBE_WHISPER_MODEL_DIR | No | Directory where whisper models are downloaded. | |
| TELEGRAM_TRANSCRIBE_WHISPER_COMPUTE_TYPE | No | Compute type for the whisper engine, e.g. int8 on CPU. | |
| TELEGRAM_RESOLVE_PHONE_MIN_INTERVAL_SECONDS | No | Minimum gap in seconds between phone lookups. 0 or unset means none. |
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
Server capabilities have not been inspected yet.
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
No tools | |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
This server cannot be deployed
Maintenance
ActivityActive
ResponsivenessNo recent community issues