Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| BOT_TOKEN | Yes | Telegram bot token from @BotFather, used to authenticate and connect to the Telegram API |
Capabilities
Features and capabilities supported by this server
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
| experimental | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| send_message | Send a text message to a Telegram chat or user. |
| send_photo | Send a photo to a Telegram chat. |
| forward_message | Forward an existing message from one chat to another. |
| delete_message | Delete a message from a chat. |
| pin_message | Pin a message in a chat. |
| get_bot_info | Return metadata about the current Telegram bot. |
| get_chat_member_info | Return role and user info for a chat member. |
| get_user_profile_photos | Return a lightweight list of Telegram profile photo file IDs. |
| get_chat_info | Get details about a chat. |
| get_chat_members_count | Get the number of members in a chat. |
| ban_user | Ban a user from a chat. |
| unban_user | Unban a previously banned user. |
| set_chat_title | Change the title of a group or channel. |
| set_chat_description | Change the description of a group or channel. |
| subscribe_events | Subscribe to real-time Telegram events. Receive notifications when new events match your filters. Read the telegram://events/queue resource to get event data. Args: chat_ids: Only events from these chats (None = all allowed chats). event_types: Filter by type: "message", "command" (None = all). |
| unsubscribe_events | Unsubscribe from real-time Telegram events. Args: subscription_id: The subscription ID returned by subscribe_events. |
| send_interactive_message | Send a message with inline keyboard buttons. Args: chat_id: Target chat ID. text: Message text. buttons: Rows of buttons. Each button: {"text": "Label", "callback_data": "value"} or {"text": "Label", "url": "https://..."}. parse_mode: HTML, Markdown, MarkdownV2, or None. disable_notification: Send silently. |
| edit_message | Edit the text and/or inline keyboard of an existing message. Args: chat_id: Chat containing the message. message_id: ID of the message to edit. text: New message text. buttons: New inline keyboard (None to remove buttons). parse_mode: HTML, Markdown, MarkdownV2, or None. |
| answer_callback_query | Answer a callback query from an inline keyboard button press. Args: callback_query_id: ID of the callback query (from the event). text: Optional notification text shown to the user. show_alert: Show as alert popup instead of toast notification. |
| send_document | Send a document/file to a Telegram chat. Args: chat_id: Target chat ID. document_url: URL or file_id of the document. caption: Optional caption. parse_mode: HTML, Markdown, MarkdownV2, or None. disable_notification: Send silently. |
| send_voice | Send a voice message to a Telegram chat. Args: chat_id: Target chat ID. voice_url: URL or file_id of the voice message (OGG with OPUS). caption: Optional caption. parse_mode: HTML, Markdown, MarkdownV2, or None. duration: Duration in seconds. disable_notification: Send silently. |
| send_video | Send a video to a Telegram chat. Args: chat_id: Target chat ID. video_url: URL or file_id of the video. caption: Optional caption. parse_mode: HTML, Markdown, MarkdownV2, or None. duration: Duration in seconds. disable_notification: Send silently. |
| send_animation | Send a GIF/animation to a Telegram chat. Args: chat_id: Target chat ID. animation_url: URL or file_id of the animation. caption: Optional caption. parse_mode: HTML, Markdown, MarkdownV2, or None. disable_notification: Send silently. |
| send_audio | Send an audio file (music) to a Telegram chat. Args: chat_id: Target chat ID. audio_url: URL or file_id of the audio (MP3/M4A). caption: Optional caption. parse_mode: HTML, Markdown, MarkdownV2, or None. performer: Performer name. title: Track title. disable_notification: Send silently. |
| send_sticker | Send a sticker to a Telegram chat. Args: chat_id: Target chat ID. sticker: File ID or URL of the sticker (WEBP/TGS/WEBM). disable_notification: Send silently. |
| send_video_note | Send a video note (round video) to a Telegram chat. Args: chat_id: Target chat ID. video_note_url: URL or file_id of the video note. duration: Duration in seconds. length: Video width and height (diameter of the circle). disable_notification: Send silently. |
| send_contact | Send a phone contact to a Telegram chat. Args: chat_id: Target chat ID. phone_number: Contact's phone number. first_name: Contact's first name. last_name: Contact's last name. disable_notification: Send silently. |
| send_location | Send a location to a Telegram chat. Args: chat_id: Target chat ID. latitude: Latitude of the location. longitude: Longitude of the location. disable_notification: Send silently. |
| send_poll | Send a poll to a Telegram chat. Args: chat_id: Target chat ID. question: Poll question (1-300 characters). options: List of answer options (2-10 strings). is_anonymous: Whether the poll is anonymous. type: "regular" or "quiz". allows_multiple_answers: Allow multiple answers (regular polls only). disable_notification: Send silently. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| moderation_prompt | Review a user's behavior and decide on moderation action. Fetches user info, chat context, and recent messages to help the AI agent make an informed moderation decision. |
| announcement_prompt | Draft a Telegram announcement message. Provides a structured template with formatting guidelines to help the AI agent compose an effective announcement. |
| user_report_prompt | Generate a comprehensive report about a user in a chat. Fetches profile data, chat membership, and message history to compile a detailed user activity report. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| bot_info | Metadata about the connected Telegram bot. |
| config | Current aiogram-mcp server configuration. |
| chats | List of active Telegram chats the bot has seen. |
| events_queue | Real-time event queue from Telegram. Returns recent events (messages, commands) received by the bot. Use subscribe_events tool to get push notifications when new events arrive. Each event has an 'id' field — use it to track which events you've seen. |
| audit_log | Audit log of all MCP tool invocations. |