Telegram MCP 0.6.0

• Upgrade note: TELEGRAM_TOOLSETS=all now also enables the new opt-in toolsets except account_admin and advanced_read, and an existing groups_admin (or all) gains remove_user, delete_forum_topic and the invite-link writes. Read-only mode and the chat ACL still apply; list toolsets explicitly if you relied on the previous set.
• Optional lazy tool loading (TELEGRAM_TOOL_LOADING=eager|lazy, default eager = unchanged): lazy lists a small core plus telegram_enable_toolsets (toolsets with one-line description and token cost); enabling makes the already-registered tools visible to that MCP session and sends notifications/tools/list_changed. Allowlists, read-only mode and approval gates still apply. Setup wizard asks eager vs lazy. Startup tokens (tools/list + instructions, ≈chars/4): eager ≈3558, lazy ≈1817. Handshake-era clients see tools.listChanged=true; hot account activation keeps not-yet-enabled tools hidden. Scope: enablement is per MCP session (FastMCP session visibility) for handshake-era clients (initialize), so one client's enabled toolsets never appear for another. Sessionless clients (2026-07-28 server/discover) and the stateless HTTP transport get a new session per request, so enablement does not persist there: use eager or TELEGRAM_TOOLSETS. README lazy section lists verified tools/list_changed client support with sources.
• Opt-in toolset event_feed: telegram_poll_events — live feed of new / edited / deleted messages from Telethon NewMessage / MessageEdited / MessageDeleted handlers, one bounded in-memory ring per account (2000 events), client-held cursor bound to the account, wait_seconds 0–55, chat_ids / kinds filters, gap=true on restart or overflow. Chat ACL applied per event; deletions without a chat (private chats, basic groups) are hidden while an ACL is set. Event text is never persisted (ids/dates only, see below). Guide telegram://guide/events.
• Opt-in toolset account_admin (stdio, telegram:write scope): telegram_add_account — QR login in chat (no phone/code/2FA password through the chat; 2FA → local wizard). Writes TELEGRAM_SESSION_STRING_<LABEL> atomically to the private secret file, never overwrites, grants the label in TELEGRAM_BINDINGS_FILE; hot-activated (see below), restart only when the result says restart_required=true.
• Competitor parity without re-pinning the vendor (zai_telegram/native.py): reads via telegram_read — get_message_by_link, export_unread_messages, get_send_as, get_member_admin_status, transcribe_voice, plus vendor export_contacts; writes via telegram_write (ledger, categories, ACL) — vote_poll, remove_user, edit_forum_topic, delete_forum_topic, rename_folder, plus vendor get_invite_link / export_chat_invite (category groups_admin).
• zai-telegram-mcp-setup --add-account LABEL [--qr] [--principal P] --directory DIR: log in one more account (phone code or QR, 2FA password via hidden prompt) into the existing secret and bindings files.
• Hot activation: an account added in chat joins the loaded runtime without restart (restart_required=false; a single-account server becomes multi-account on the fly). Restart is still needed for the label default or if activation fails (only a pure addition of TELEGRAM_SESSION_STRING_<LABEL> is accepted; any other secret change still needs a restart). Fixes the running server refusing calls after the secret file gained a new session.
• Event feed survives restarts: epoch, sequence and event ids (never text) persist for 24 h in the state DB; old cursors stay valid and only the downtime is reported as gap_window. TELEGRAM_FEED_PERSIST=0 disables.
• Vendor backports from chigwell/telegram-mcp after v3.2.0 (vendor/patches/zai-backports-2026-10.patch, recorded in the manifest): serialized reconnects per client (2980601), no interactive start() on reconnect plus 30 s reconnect timeout (dd71a12), list_messages search starting at to_date (312cd00), custom custom:<id> and empty reactions (7fc6b4a).
• Live reload: the server watches its secret and bindings files; a pure session addition is hot-added, new grants apply on the next call, the redaction set refreshes, and when the server becomes multi-account every tool gains account and telegram_list_accounts appears (MCP tools/list_changed). account_admin exposes account from the start. Invalid bindings keep the previous grants.
• Event feed: downtime backfill (messages sent while the server was down become new events with backfilled=true, bounded 100 dialogs / 500 messages, TELEGRAM_FEED_BACKFILL=0); quiet accounts keep alive_at fresh.
• Vendor backport d5ddc8c: get_participants paginates without the non-existent Telethon offset argument (every call failed before).
• Owner follow-up: get_message_by_link now works under a chat ACL — the chat named in the link is checked (unparsable links are denied); t.me/s/<name>/<id> links; transcribe_voice(wait_seconds 0–30) waits for the final text (updateTranscribedAudio); rename_folder also renames imported shared folders. Native tools reconnect like vendor tools; remove_user refuses self; vote_poll rejects closed polls and repeated options.
• Critic fixes: newly saved sessions are redacted even when activation fails; abandoned QR logins are disconnected after 10 min; in-chat grants work without a bindings file path (reported as binding_saved=false).
• Review fixes: in-chat QR login keeps Telethon's wait running between status calls, so a scan made before status is no longer lost; the new label is saved to the bindings file even after the embedded runtime cleared TELEGRAM_* variables; telegram_add_account is never registered on HTTP; TELEGRAM_FEED_BACKFILL=0 is honoured; telegram_poll_events no longer blocks the event loop when the ring lost events behind the cursor, and refuses to run (chat_access_denied) while TELEGRAM_DENIED_CHATS names a chat by @username (feed events carry numeric ids only); delete_forum_topic repeats until the whole topic is deleted (partially_deleted after 50 batches).
• Skeptic review fixes (Security/Fix): telegram_add_account now requires TELEGRAM_WRITE_ENABLED and an enabled provider (checked before the QR login and again before saving) and is removed by read-only mode even when named in TELEGRAM_TOOLS; session + binding updates (in chat and --add-account) run under one cross-process file lock with the label re-checked inside it, so concurrent adders never lose a session or grant; telegram_poll_events is admitted like every read (provider switch, cooldown, rate limit, concurrency lease held during the wait); ring overflow during a long-poll wait is reported as gap=true; downtime backfill reports backfill_complete=false when more than 100 dialogs changed; export_unread_messages returns the unread incoming messages above the read marker (later outgoing messages no longer displace them) and flags truncated.
• Router: same lines, now also routing live feed and add-account; default/all always-loaded context stays at or below 0.5.0 (enforced by scripts/token_budget.py). Router eval: 34 cases, optional upstream-tool check.

Source: d93a70f · Changes: v0.5.0...v0.6.0

Telegram MCP 0.5.0

• License: LicenseRef-ZAI-ONE 2.0 (source-available). Free install and use for yourself and your organisation, including commercial work; issues and pull requests welcome; copying code into other projects, redistribution, embedding and competing hosted services need written permission. Earlier releases keep their LicenseRef-ZAI-ONE 1.0 terms (see NOTICE). README first screen: one-line scope, why this MCP, maintenance and update check.
• Toolsets (TELEGRAM_TOOLSETS, TELEGRAM_TOOLS, TELEGRAM_DISABLED_TOOLS, --toolsets), read-only mode (TELEGRAM_READ_ONLY, --read-only) and write categories for telegram_write. Unset = previous surface.
• Per-chat ACL: TELEGRAM_ALLOWED_CHATS (deny-by-default when set) and TELEGRAM_DENIED_CHATS; listings are filtered.
• Compact tool descriptions and titles; router instructions as intent → first tool → skill/guide, with a fallback to telegram://playbook; error envelopes gain hint and docs; new codes chat_access_denied, tool_disabled.
• Resources telegram://toolsets, telegram://playbook, telegram://guide/{topic}; prompts inbox_digest, publish_post, chat_research.
• Self-contained skills (skills/, including telegram-channel-report and telegram-watch-replies), Claude Code plugin + marketplace (.claude-plugin/), server.json, scripts/token_budget.py (CI via tests).
• Compact replies: TELEGRAM_RESPONSE_DETAIL=summary (+ TELEGRAM_MAX_TEXT_CHARS) drops empty fields and truncates long texts with explicit markers; default full is unchanged.
• New read tools (toolset chat_insights): telegram_list_topics, telegram_get_admins, telegram_get_chat_stats (vendor patch over Telethon get_stats → stats.getBroadcastStats / stats.getMegagroupStats).
• Opt-in toolset advanced_read: generic telegram_read(tool, arguments) over 43 reviewed read-only Telethon tools (participants, pinned, reactions, read-by, message links/context, folders, drafts, contacts, profiles, admin log...). Never part of all. Guide telegram://guide/advanced-read.
• Multi-account with labels: list-valued bindings ({"actor": ["default", "work"]}, first = default) add an optional per-call account argument to every tool and telegram_list_accounts; rate limits, poll cursors and outbox idempotency are per account, and telegram_outbox_status records carry account_label. String bindings keep the previous schema byte-for-byte.
• telegram_wait_for_new_message (toolset events): bounded long-poll (1–55 s) over 1–10 chats with a local baseline, paced reads and status=timeout; respects the chat ACL; no read receipts.
• telegram_wait_for_settled_message (toolset events): poll-based debounce — waits until watched chats go quiet for settle_seconds (1–30, default 6) after new messages; status=settled, partial with pending messages, or timeout. Same ACL and read pacing as telegram_wait_for_new_message.
• One-minute install: uvx --from git+https://github.com/zai-one/telegram-mcp@v0.5.0 zai-telegram-mcp-setup; the wizard writes a uvx client entry pinned to the installed release tag when run from uvx (ZAI_TELEGRAM_UVX_FROM overrides the source). The Claude Code plugin and README snippets pin the same tag.
• Router eval (tests/eval/router_cases.json, 26 colloquial EN/RU requests) checks router → skill/guide → first tool, and fails if any tool, skill or guide is unreachable from the router. Token budget now also caps the always-loaded context (instructions + tools/list + skill frontmatters, ≈3.9k tokens default).
• Vendor fixes: GIF search uses the @gif inline bot (Telethon has no messages.SearchGifsRequest); import_contacts uses types.InputPhoneContact.
• Security: under TELEGRAM_ALLOWED_CHATS the generic telegram_write fails closed — a call must name an allowed chat (or, without a chat, an allowed user_id/channel), and account-wide or chat-creating writes (join by link, create group/channel, profile, privacy, folders, contacts import) are denied. Under any chat ACL telegram_read needs a named chat/user: account-wide reads (contacts, drafts, global search, folders) and chat-listing reads (get_common_chats, get_contact_chats) are denied.
• Fix: telegram_wait_for_settled_message no longer acknowledges already-watched chats when a new chat joins the wait, so their unread messages are returned instead of dropped; its settle loop is paced like telegram_wait_for_new_message (~24 reads/min).

Source: 5bc45ce · Changes: v0.4.0...v0.5.0

Telegram MCP 0.4.0

• Telethon 1.44.0 → 1.45.0 (MTProto layer 227 → 229), backward-compatible: types.User, types.Channel, types.ChatAdminRights and types.ChatBannedRights only gained optional trailing keyword arguments.
• MCP tool annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) on every tool, matching the telegram:read/telegram:write split. Hints only; scopes, bindings and the write allowlist still enforce access.
• telegram_check_update: read-only, suggest-only check of the latest GitHub release with release notes link and update command (3 s timeout, 24 h cache, offline result). A cached newer release adds a one-line startup hint; a stale cache is refreshed on a background thread. Opt out with TELEGRAM_MCP_DISABLE_UPDATE_CHECK=1.
• The update check goes through the same registrar as the Telegram tools (stdio local scopes, account binding, audit, per-account quota). Only plain version tags (v1.2.3) and this repository's release URLs are reported; failed requests back off for 30 minutes and force=true is honoured at most once a minute.
• The clean-install gate disables the update check and blocks external DNS in its server process.

English setup · Описание по-русски

Download the wheel or source archive below and verify SHA256SUMS. The installed setup
command generates local JSON/TOML client configuration; a source checkout is optional.
Your own provider credentials and API permissions remain required.

Verified on Python 3.12, 3.13 and 3.14 on Linux and Windows: existing contracts,
synthetic functional tests, clean wheel installation and real MCP stdio checks.
Live provider accounts and production deployment were outside this release verification.
GitHub verification · Source commit 095cd179757e4ac18ea3fec244d2313488ea5e25.

ZAI.ONE is a digital agency for websites, SEO, advertising and analytics.
ZAI.ONE — интернет-агентство: сайты, SEO, реклама и аналитика.
Contact / Написать в Telegram about setup and integration.

LicenseRef-ZAI-ONE permits installation and internal use on your own or authorized
accounts; it is not an open-source license. Third-party rights remain unchanged.
Stars are welcome. Request changes through Issues.

Telegram MCP 0.3.0

• Operator-owned media folders, bounded files/albums/voice notes and exclusive bounded downloads to a separate folder; existing account, write policy and durable outbox retained.
• Explicit numeric destination checks for media and polling, with no caller-controlled roots.
• Poll selected chats after acknowledged message IDs; first poll proposes a current baseline. Durable actor/account-bound batches, atomic acknowledgment and safe replay across restart.
• Installable setup wizard and JSON/TOML client snippets that work outside the checkout.
• English and Russian agency information, integration contact and package installation guide.

English setup · Описание по-русски

Download the wheel or source archive below and verify SHA256SUMS. The installed setup
command generates local JSON/TOML client configuration; a source checkout is optional.
Your own provider credentials and API permissions remain required.

Verified on Python 3.12, 3.13 and 3.14 on Linux and Windows: existing contracts,
synthetic functional tests, clean wheel installation and real MCP stdio checks.
Live provider accounts and production deployment were outside this release verification.
GitHub verification · Source commit 00bc8b09f20f075cce01e33f84a27d690b05f7bb.

ZAI.ONE is a digital agency for websites, SEO, advertising and analytics.
ZAI.ONE — интернет-агентство: сайты, SEO, реклама и аналитика.
Contact / Написать в Telegram about setup and integration.

LicenseRef-ZAI-ONE permits installation and internal use on your own or authorized
accounts; it is not an open-source license. Third-party rights remain unchanged.
Stars are welcome. Request changes through Issues.

Telegram MCP 0.2.0

Install Telegram MCP on your own computer or server and connect an MCP client.

• Quick start and installation guide.
• Changes in 0.2.0.
• Python 3.12, 3.13 and 3.14 verified on Linux and Windows. Clean wheel installation, real stdio discovery and source-distribution builds passed using synthetic fixtures.
• Provider credentials and API access remain required. Live provider validation is an operator step.
• Proprietary LicenseRef-ZAI-ONE: install and use for your own or authorized accounts. Separately identified third-party licenses remain unchanged. Stars welcome; request improvements through Issues.

Download the wheel or source archive below; verify it against SHA256SUMS.
Exact source commit: 416a1021eb50681a0a9573b1fc80869984cb8be8. Verification run.