overpod/mcp-telegram

GramJS Coverage Phase 1 — 15 new tools

Expands MCP coverage toward parity with a regular Telegram client. Focus: messaging, dialogs, drafts, admin tools, reactions, search and media.

Added

Messaging & threads

• telegram-get-scheduled — list scheduled messages in a chat
• telegram-delete-scheduled — delete scheduled messages (capped 1–100)
• telegram-get-replies — read comments under a channel post or discussion thread
• telegram-get-message-link — public t.me URL for a message
• telegram-get-unread-mentions — fetch unread @mentions (marks them read)
• telegram-get-unread-reactions — fetch unread reactions (marks them read)
• telegram-translate-message — translate messages (requires Telegram Premium)
• telegram-send-typing — typing / uploading indicator with 10s per-chat throttle

Dialogs & drafts

• telegram-archive-chat — move chat to archive or back
• telegram-pin-chat — pin/unpin a dialog
• telegram-mark-dialog-unread — mark dialog as unread
• telegram-save-draft — save or clear a draft (clearing drops replyTo to avoid MESSAGE_EMPTY)
• telegram-get-drafts — list all drafts across chats
• telegram-clear-drafts — clear draft(s); requires chatId OR confirmAllChats: true to wipe account-wide
• telegram-get-saved-dialogs — new per-peer Saved Messages folders

Admin / channels / groups

• telegram-get-admin-log — channel/supergroup moderation history with user and action details
• telegram-set-chat-permissions — default banned rights (merges with current to keep omitted flags)
• telegram-set-slow-mode — slow mode seconds for supergroups
• telegram-create-topic / telegram-edit-topic / telegram-delete-topic — forum topics CRUD

Reactions & media

• telegram-set-default-reaction — set account-wide default reaction emoji
• telegram-get-top-reactions / telegram-get-recent-reactions — reaction discovery
• telegram-get-web-preview — link preview (http(s) only; no SSRF)

Safety hardening during review

• telegram-clear-drafts now requires chatId or explicit confirmAllChats: true to prevent accidental account-wide draft wipe.
• telegram-get-unread-mentions / telegram-get-unread-reactions reclassified as WRITE — calling them marks items read on the server.
• telegram-translate-message reclassified as WRITE (consumes Premium quota); toLang validated against ISO 639-1 / locale pattern.
• Array inputs capped at 1–100 positive integers in translate-message and delete-scheduled.
• telegram-get-web-preview rejects non-http(s) URLs, preventing use as an SSRF proxy.
• telegram-set-chat-permissions merges with the chat's current defaultBannedRights — omitted flags keep their current state instead of being silently cleared.
• telegram-create-topic reads the new topic ID from UpdateNewChannelMessage (authoritative) and fails loudly if unavailable.

Infrastructure

• All new service methods go through rateLimiter.execute() for FLOOD_WAIT handling.
• All text outputs sanitize unpaired UTF-16 surrogates before JSON serialization.
• 3 new unit test files (admin-log, reactions, set-chat-permissions merge).

Install

npm install -g @overpod/[email protected]

or via npx @overpod/mcp-telegram for zero-install.