Telegram MCP
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| apiId | Yes | Telegram API ID from my.telegram.org, required in config.json | |
| apiHash | Yes | Telegram API hash from my.telegram.org, required in config.json | |
| allowSending | No | Enable send_message; each message still requires explicit user approval | false |
| allowedChats | No | Chats that may be read | [] |
| verbosityLevel | No | TDLib log verbosity written to stderr | 1 |
| maxMessageLimit | No | Upper bound for limit parameters | 100 |
| TELEGRAM_MCP_DEBUG | No | Set to 1 for verbose MCP-level logging to stderr | |
| allowChatDiscovery | No | Enable discover_chats metadata listing | true |
| TELEGRAM_MCP_CONFIG | No | Absolute path to config.json | |
| defaultMessageLimit | No | Default page size | 30 |
| tearOffMessageTextAt | No | Maximum characters per message text | 4000 |
| TELEGRAM_MCP_DATA_DIR | No | Absolute path for the TDLib database and files | |
| daemonIdleTimeoutSeconds | No | Idle time before the shared daemon exits | 600 |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Telegram access restricted to an allowlist of chats. If not signed in, call auth_status, then auth_start/auth_code/auth_password. Reading is always available for allowlisted chats. send_message is the only write operation: it is disabled unless enabled in config, and every message shows the user an approval prompt. Nothing is sent unless the user approves; if they decline, do not retry unless they ask. Editing, deleting, forwarding, joining, and leaving are impossible.
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 |
|---|---|
| auth_statusA | Check whether the Telegram session is signed in and which login step is required. Start here if Telegram tools return an authentication error. |
| auth_startA | Start phone-number login. Telegram sends a login code to the account. After calling this, call auth_code with the code, and auth_password if two-step verification is enabled. |
| auth_codeC | Submit the login code Telegram sent to the account. |
| auth_passwordA | Submit the two-step verification password, if the account has one enabled. |
| auth_logoutA | Log out and destroy all local Telegram session data. This requires network access and cannot be undone without logging in again. |
| discover_chatsA | List chat ids and titles to help populate the allowlist. This returns metadata only, never message contents. Requires allowChatDiscovery in config.json. Pass a query to search, or omit it to list top chats. |
| list_allowed_chatsB | List every chat in the allowlist, with ids, types, usernames, and any resolution errors. |
| get_chatA | Get details about one allowlisted chat: title, type, username, member count, and description. |
| get_messagesA | Read recent messages from one allowlisted chat, oldest first. Paginate older messages by passing the previous nextBeforeMessageId as beforeMessageId. |
| search_messagesA | Search messages by text inside one allowlisted chat, or across all allowlisted chats. Results are newest first. |
| get_messageA | Fetch a single message by id from an allowlisted chat. |
| send_messageA | Send a plain-text message to one allowlisted chat as the signed-in user. Requires allowSending in config.json. Every call shows the user an approval prompt with the exact chat and text; nothing is sent unless the user approves. Returns sent: false if the user declines. Do not retry a declined message unless the user asks. |
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 12 tools
Each tool has a distinct purpose: authentication steps are sequential and clearly separated, chat tools cover discovery/listing/details, and message tools cover listing, searching, fetching one, and sending. There is little risk of confusing one tool for another.
All tool names use consistent snake_case with clear verb_noun or auth_* prefixes. The pattern is predictable across authentication, chat, and message operations.
Twelve tools is well-scoped for a Telegram MCP server, covering authentication, chat discovery, message reading, search, and sending without excessive surface area.
The server covers the core lifecycle: login/logout/status, chat discovery and allowlist inspection, message reading/searching, and sending. Minor gaps exist around message editing/deletion, replies, and media, but core workflows are supported.