Telegram MCP Server

Sends text messages, media files, and formatted content to Telegram chats and channels through the Telegram Bot API. Implements message routing logic that resolves chat identifiers (numeric IDs, usernames, or channel handles) to API endpoints, handles message formatting (Markdown/HTML), and manages delivery confirmation through API response parsing. Supports batch message operations and message editing after delivery.

Retrieves message history from Telegram chats and channels by querying the Telegram Bot API for recent messages, with filtering by date range, sender, or message type. Implements pagination logic to handle large message sets and parses API responses into structured message objects containing sender info, timestamps, content, and media metadata. Supports reading from both private chats and public channels.

Integrates with Telegram's webhook system to receive real-time updates (messages, callbacks, edits) via HTTP POST requests. The MCP server can be configured to work with webhook-based bots (alternative to polling), receiving updates from Telegram's servers and routing them to connected LLM clients. Supports update filtering and acknowledgment.

Translates Telegram Bot API errors and responses into structured MCP-compatible formats. The MCP server catches API failures (rate limits, invalid parameters, permission errors) and maps them to descriptive error objects that LLMs can reason about. Implements retry logic for transient failures and provides actionable error messages.

Registers custom bot commands (e.g., /start, /help, /custom) and routes incoming Telegram messages containing those commands to handler functions. Implements command parsing logic that extracts command names and arguments from message text, matches them against registered handlers, and invokes the appropriate handler with parsed parameters. Supports command help text generation and command discovery via /help.

Fetches metadata about Telegram chats and channels including member counts, titles, descriptions, pinned messages, and permissions. Queries the Telegram Bot API for chat information and parses responses into structured objects. Supports both private chats and public channels, with different metadata availability depending on bot permissions and chat type.

Retrieves information about Telegram users and chat members including usernames, first/last names, profile pictures, and member status (admin, restricted, etc.). Queries the Telegram Bot API for user objects and member information, with support for looking up users by ID or username. Returns structured user profiles with permission and status flags.

Edits or deletes previously sent messages in Telegram chats by message ID. Implements message lifecycle management through Telegram Bot API endpoints, supporting text content updates, media replacement, and inline keyboard modifications. Handles permission checks and error cases (e.g., message too old to edit, insufficient permissions).

Creates interactive inline keyboards with buttons that trigger callback queries when clicked, and handles incoming callback data from button presses. Implements button registration and callback routing logic that maps button IDs to handler functions. Supports button state management and dynamic keyboard updates based on user interactions.

Uploads files and media to Telegram chats through the Telegram Bot API, supporting documents, images, audio, video, and other file types. Implements file type detection, size validation, and upload streaming for large files. Handles file ID caching to avoid re-uploading identical files and manages media metadata (captions, thumbnails, duration).

Performs administrative operations on Telegram groups and channels including adding/removing members, setting permissions, pinning messages, and managing group settings. Implements permission-aware operations that check bot admin status before executing changes. Supports bulk operations (e.g., removing multiple members) and permission configuration through structured objects.

Listens for incoming Telegram messages and events through either webhook (push-based) or long-polling (pull-based) mechanisms. Implements event routing that dispatches incoming messages to registered handlers based on message type (text, command, media, etc.). Supports both update types and provides abstraction over the transport mechanism (webhook vs. polling).