v0.8.0

Outbound policies

• Add local-only all-chat write access and one-off confirmed sends to new people or private bots. Keep action flags separate and leave recipient lists unchanged; retrieval permissions, service-notification exclusions and unsupported-action checks remain enforced.
• Add independent strict TOML switches for message, file, callback and user-draft overwrite forms. Defaults preserve required confirmations; one-off grants always require a form. Report exact policies and aggregate confirmation requirements in get_status.
• Bind new send operations to their original numeric recipient across username reassignment, restarts and payload cleanup. Persist the permission basis and distinguish configuration authorization from form approval; stricter confirmation settings require approval before an unapproved retry. One-off/all-chat send receipts remain readable after permission revocation without permitting another send.

Outbound inspection and diagnostics

• Open private SQLite files in binary mode on Windows so preparation cannot strip a trailing Ctrl+Z byte and corrupt data. Rebuild the affected derived journal date index while preserving operation JSON, receipts and idempotency keys. This fixes intermittent OUTBOUND_STORAGE_UNAVAILABLE failures during receipt updates.
• Add recipient metadata previews without history, exact sent-message verification and account-bound operation recovery by key or paginated journal filters. Preserve original receipts separately from fresh read-back and text/attachment metadata comparisons; verification grants no access to surrounding history or attachment bytes. Migrate journal indexes without discarding legacy records or inventing unknown dates.
• Report the running server and connect versions separately in get_status, with the server start time and packaged build commit when known. Freeze process identity across in-place updates and preserve source identity when rebuilding a wheel from an sdist.

Security

• Update locked pyasn1 from 0.6.4 to 0.6.5 for four ASN.1 decoder CPU-exhaustion advisories (GHSA-fm9c-5rcf-2q5p, GHSA-9m75-vc3g-4x39, GHSA-2qm8-x737-gmw5 and GHSA-mm57-4v3p-rchx). The 0.8.0 MCPB includes the patched dependency; replace older bundles to receive it.

Upgrade and validation

• Upgrade the shared server and client proxies to 0.8.0, restart both, and refresh client tools. Keep the [extraction] extra when upgrading a server that reads PDF/DOCX files. Existing write flags, recipient allowlists and required forms retain their defaults; upgrading does not enable broader access or disable confirmation.
• Preserve the session-adjacent outbound database and reusable files. Journal migration is automatic and retains receipts and idempotency keys; the Windows repair rebuilds only the affected derived date index. No outbound state downgrade is supported.
• See the 0.8.0 validation record for release checks and live coverage limits.

v0.7.0

Reading

• Preserve message button rows, text, types and URLs without exposing callback payloads. Message revisions include button changes and remain stable across text continuation and volatile counters. Add the raw Telegram outgoing flag, selected-source direction filters and channel membership metadata.
• Omit recognized English/Russian authentication notices before message delivery, checkpoint/watch payload persistence and new exports; omit associated entities, previews, buttons and attachments. Deny direct downloads, extraction and imports of those notices. The classifier is conservative, not a guarantee against every credential format; existing permanent archives are not rewritten.

Optional outbound workflows

• Add separately enabled native drafts, message/file sending and private-bot callbacks. Recipients require ordinary read access and an explicit write allowlist; all capabilities default off. Outbound tools appear only when a write capability is enabled. Sending and callbacks require client form confirmation; replacing a user draft also requires confirmation and its current revision.
• Register immutable files from selected Telegram attachments or allowed local directories, retaining name, MIME type, size and SHA-256. Support one file with a caption in confirmed sends. Native drafts support plain text only; file drafts are deferred and return DRAFT_ATTACHMENT_UNSUPPORTED before any upload or write. Local maintenance lists/removes files and inspects operation receipts without contacting Telegram.
• Persist account-bound idempotency keys and random IDs before sending. Repeated keys replay receipts, conflicting requests fail, uncertain sends retain their random ID, and uncertain callbacks never re-execute. Preserve deduplication records without FIFO eviction and refuse new operations at quota. Persist scoped Telegram cooldowns across restart.
• Support legacy elicitation and modern MCP confirmation rounds through STDIO, authenticated HTTP and connect. Confirmation waits release tool capacity; permission, recipient, content and account checks run again before dispatch. Telegram mutations have no automatic RPC/reconnect replay; explicitly selected reads retain one bounded server-error retry.
• Fix get_send_status returning an unexpected MCP error: return the send/callback receipt inside result, matching its advertised union output schema. Persisted operation records and direct send responses are unchanged.

Documentation

• Document outbound permissions, operation recovery and client limitations; update the optional Agent Skill. Add compact Glama, mcprush and XERJ Corpus Hub directory badges.

Upgrade and validation

• Upgrade the shared server and client proxies to 0.7.0, restart the server and refresh client tools. Existing read configurations remain read-only; no write capability or recipient is enabled by upgrading. Native Telegram sessions, checkpoints and watches remain supported.
• Keep the [extraction] extra when updating a server that reads PDF/DOCX files. Outbound features require separate local capability flags and explicit write recipient IDs; sending and callbacks also require a client that supports human form confirmation. See the outbound guide.
• Preserve the session-adjacent outbound database and reusable-file storage across upgrades; deleting operation records loses durable duplicate-send protection. No outbound state downgrade is supported.
• Selected-source live validation in Codex confirmed form acceptance/refusal, text drafts and conflicts, file integrity, duplicate receipts across restart, direction filters, synthetic authentication-notice omission before archive, and one explicitly selected bot callback with revision rejection and receipt replay. See the 0.7 validation record for evidence and client coverage limits.

v0.6.0

Extraction

• Optional local PDF/DOCX text extraction through telegram-context-mcp[extraction]. extract_attachment_text reads one selected attachment and returns bounded Unicode text slices with source digests and physical PDF page references. Temporary results expire after 15 minutes and recheck source access and media identity on every read.
• Document parsing runs in a terminable subprocess with explicit input, page, text, expansion and time limits. Unsupported, encrypted, damaged and textless documents have distinct errors; DOCX body-only omissions and PDF pages without text are reported. get_status advertises availability without requiring the extra for ordinary tools.
• Recover structurally damaged PDFs with one bounded tolerant retry, reported as DOCUMENT_RECOVERED; accept PDF signatures within the first 1024 bytes and preserve original source digests and page provenance. Resolve DOCX main parts through OPC relationships and report macro-enabled DOCM as unsupported.
• Cap each expanded DOCX entry at 32 MiB and Linux worker address space at 1 GiB (or a stricter inherited limit). Allocation failures report EXTRACTION_LIMIT_EXCEEDED; Windows/macOS retain the existing time and document budgets without an OS memory cap.
• Avoid a redundant source request between attachment download and parsing while retaining fresh permission and attachment checks before delivery and on continuation.

Authentication

• telegram-mcp login --qr displays a terminal QR for approval in the Telegram phone app, with optional 2FA and up to three expiring codes per invocation. It reuses the configured session, keeps the existing phone/code flow, and requires no external QR executable. Cancellation and failures release the session; rate limits report the wait without sleeping. Tokens and raw authorization responses are not printed.

Distribution

• Optional Linux systemd user unit and installation/lifecycle guide for the shared HTTP server. It runs a persistent installed executable, restarts after crashes, and preserves the existing local authentication and session ownership model. The unit works with published 0.5.1; no package upgrade is required to adopt it.
• Preview Claude Desktop MCPB packaging with a shared-server connect launcher, external configuration-file selection, the matching release wheel and locked runtime dependencies. CI checks reproducible archives and isolated launches on Linux, Windows and macOS; GitHub releases include the bundle and SHA-256 separately from the PyPI artifacts. Initial Windows Desktop connection and catalog checks passed on Windows 11 25H2 with Claude Desktop 4.29.0. Additional Desktop UI/lifecycle scenarios and macOS Desktop remain manually unverified. See the bundle guide.

Agent Skill

• Add an optional MIT-licensed telegram-mcp Agent Skill for source-linked reading, bounded digests, watch acknowledgement and selected attachments, with client installation instructions. It uses existing MCP tools and does not change server permissions or install automatically with the Python package.

Dependencies

• Refresh the locked HTTP/SSE and TLS dependencies, including Starlette 1.10.0, sse-starlette 3.6.0, cryptography 50.0.2 and truststore 0.10.5, with supporting parser, IDNA and test-plugin updates. Dependency constraints and MCP contracts are unchanged.
• Update pytest-asyncio to 1.4.1 and group its test stack's iniconfig and pluggy updates with development tools in Dependabot.

Upgrade and validation

• Upgrade the shared server and client proxies to 0.6.0, restart the server and refresh client tools. Existing sessions, permissions, checkpoints and subscriptions remain compatible; no state migration is required.
• For PDF/DOCX support, install or update the session-owning server with uv tool install --python 3.12 'telegram-context-mcp[extraction]==0.6.0' and enable allow_attachment_downloads. The extra is not needed by connect or the MCPB proxy.
• See the 0.6.0 validation record for autonomous checks, selected-document live validation and client coverage limits.

v0.5.1

Security patch for 0.5.0; upgrading is recommended for every installation.

Security

• Telegram service notifications (777000), which deliver login codes, are never readable: all-chat and folder access exclude them, explicit reads and monitoring, export or download requests return ACCESS_DENIED, and configuration that allowlists them is rejected. Previously allow_all_chats or a folder containing this chat let a prompt-injected agent read a login code.
• Access checks reject noncanonical numeric chat IDs before all-chat, explicit, public-channel or same-source grants. Unicode-digit aliases previously bypassed the service-notification deny rule in message and context reads. allowed_chat_ids also requires ASCII decimal IDs without leading zeros or extra characters.

Development

• R6 structural consolidation: MCP tools and wire DTOs are organized by feature, complex query, change, watch, storage and Telegram reader functions are split into named steps, and Ruff enforces a McCabe complexity limit of 15. Tool schemas, descriptions, error codes and persisted formats are unchanged.
• Tests run in parallel through pytest-xdist; make test-fast skips tests marked slow. New fixtures pin tool order and descriptions, wire/domain field parity and 0.5 state.

Compatibility and validation

• Tools, prompts, schemas and persisted state are unchanged; no client refresh is needed. Upgrade the shared server and client proxies together and restart the server.
• A configuration whose allowed_chat_ids contains 777000 now fails with INVALID_CONFIGURATION; remove that entry or run telegram-mcp configure.
• Noncanonical allowlist IDs also fail configuration validation. Use the ASCII decimal ID returned by Telegram MCP, without leading zeros, a plus sign or whitespace.
• See the validation record for offline and selected-source checks.

v0.5.0

Added

• get_history reads several selected chats (chat_ids) or folders (folder_ids) over a fixed [date_from, date_to) period in one traversal. It defaults to early ordering="page" results and cumulative max_sources=20 / max_messages=100 budgets; a larger selection returns SOURCE_LIMIT_EXCEEDED before any history read, and a typed budget object reports exhaustion while keeping the cursor resumable.
• get_watch_changes(save=true) writes each pending batch to a permanent JSONL copy with metadata.json (watch, batch and sources) before it can be acknowledged and returns saved_file. Retries, lost responses, restarts and crashes reuse the same copy; WATCH_ARCHIVE_PENDING and ARCHIVE_COPY_INVALID keep positions unchanged.
• MCP prompts watch_digest and period_digest for source-linked digests, with explicit trust rules for Telegram content, bounded workflows and a documented vacancy preset; completion for watch_digest.watch_name from local storage only. Both are forwarded by connect.
• timezone configuration (IANA name, default UTC) for calendar dates in prompts.
• MCP Registry metadata for io.github.egor-fedorov/telegram-mcp, validated against the package version and published after PyPI through GitHub OIDC. A separate workflow retries Registry publication without rebuilding or uploading the package. The first Registry entry requires a release containing this integration.
• telegram-context-mcp as an alias of the existing telegram-mcp CLI, allowing Registry clients to use the package's default uvx executable.

Compatibility and validation

• All changes are additive: existing tool arguments, single-chat history responses and save=false watches behave as in 0.4.0. Refresh client tool lists to see the new get_history and get_watch_changes arguments.
• Windows installations now include tzdata, because Windows has no system time-zone database.
• Upgrade the shared server and client proxies together, restart the server, and refresh client tools and prompts. watch_digest saves batches by default: configure archive_directory, or explicitly choose save=false and acknowledge after delivery.
• Selected-source live checks verified bounded multi-source reads, saved-batch recovery across restarts and acknowledgement, plus a Claude Code 2.1.310 digest workflow and watch-name completion. See the validation record for coverage.

v0.4.0

Added

• Opt-in download_attachment for a selected photo or document up to 20 MiB, with SHA-256, a private local file and an MCP resource. The 100 MiB / 32-file cache expires after 15 minutes; reads recheck access, protection and media identity.
• get_changes for new messages and bounded recent revisions in one selected chat. Durable checkpoints survive restart without storing message bodies, retain FloodWait deadlines and report unavailable messages without claiming deletion.
• export_history and JSONL/Markdown output from get_changes, preserving original text, metadata and source links in bounded, restartable parts. History exports freeze their upper date/ID and omit protected or expiring records explicitly.
• Named chat/folder subscriptions through create_watch, list_watches, get_watch_changes, ack_watch_changes and delete_watch. Positions and one unacknowledged batch survive restart; polling is on demand. ack_batch_id acknowledges processed data and polls in one call, with safe duplicate retries.
• Optional archive_directory and save=true for permanent selected downloads and exports. Each copy includes versioned metadata.json provenance, original name, MIME type, checksum and export boundaries. Publication and rollback use bounded worker threads so disk writes do not block other calls.
• Offline telegram-mcp checkpoints status/prune, with preview by default and explicit flags for deleting protected positions under the session lease.
• Bounded opt-in live probes for selected downloads, checkpoints, exports and peer metadata, with redacted reports and disposable-state cleanup.

Changed

• Breaking response contract: scope.chat_ids and pending_chat_ids preview at most 20 IDs, with exact counts and truncation flags. Authorization and continuation retain the full scope. See the migration guide.
• Changed search default: restricted search_messages uses ordering="page" to return results before every source is initialized. Select ordering="global" for ordering across pages. Both traversal directions remain available.
• Dialog snapshots default to 300 seconds of reuse plus 300 seconds during one shared background refresh. Authorization and folder definitions remain fresh; ordinary connection failures preserve catalog progress and usable snapshots.
• STDIO, HTTP and connect share four active calls, 16 FIFO waiters and a 120-second queue timeout. Independent incremental reads can overlap; subscription operations serialize only by name. Downloads remain serialized.
• Watches compare selected channel/supergroup heads and pts in batches of 100. Completed unchanged sources skip history reads; unsupported markers and observed polls retain ordinary revision checks. Creation accepts 20 explicit references, deduplicates aliases and has a 35-second deadline; folders cover larger selections.
• Current checkpoint heads retain 30-day protection. Equivalent positions reuse tokens; fresh starts protect one unused baseline per source and authorization. Consumed chains and independent branches remain protected. Version-3 migration conservatively retains ambiguous legacy roots; offline cleanup can recover a full store.
• Compact tool discovery omits optional output schemas by default while retaining typed validation and identical JSON responses. Set mcp_schema_mode="full" to advertise them. The full surface now contains 22 tools.
• Organized tests by layer and separated Telegram search, topic-history and album readers. Updated ty to 0.0.92 and Ruff to 0.17.2; Dependabot separates development tooling and retains manual review. CI/release actions use reviewed pinned updates.
• Updated locked MCP packages to 2.3.0, the HTTP stack and platformdirs after compatibility checks across STDIO, HTTP and the bridge.

Security

• Updated locked PyJWT to 2.15.1 and OpenTelemetry API to 1.45.1 for reported vulnerabilities in transitive dependencies. Local HTTP still requires its bearer token.

Compatibility and validation

• Existing Telegram sessions and source permissions remain supported. New downloads and permanent copies require explicit opt-ins. After upgrading, restart the server and refresh client tool schemas; do not downgrade a migrated checkpoint database.
• Offline checks cover Python 3.12–3.15 and all three transports. Selected-source live checks cover photo/video downloads, export integrity, durable monitoring and reconnect. See the validation record for measurements and coverage limits.

v0.3.0

Added

• Automatic bounded reconnection after a lost Telegram connection, with fresh authorization checks and retry deadlines.
• A 30-second completed-catalog cache and resumable, bounded cold loads that return CATALOG_LOADING; direct reads independent of folders bypass catalog scans.
• Account-dialog global search with all-chat permission, fair restricted-source preparation with progress, native URL/photo/voice/audio filters, has_link, and webpage preview metadata.
• Typed responses for all 14 tools, deterministic payload/schema size regression checks, and an opt-in bounded live-validation script for explicitly selected sources.

Changed

• Breaking output contract: message references are canonical strings; message responses share brief chat summaries; unknown optional metadata is omitted. list_folders returns {folders: [...]}. Full compact JSON appears in both text and structured content. See migration guidance.
• Restricted search uses numeric chat IDs for same-second ordering; global search keeps Telegram's order within equal timestamps. Search preserves its selected search engine, date ceiling, and scope across continuation calls.
• Raw message mapping no longer calls Telethon's private _finish_init method. Preview images/files no longer become standalone message attachments.

Compatibility and validation

• Existing read permissions, input references, session files, STDIO, local HTTP, and the bridge remain supported. Global search is restricted to all-chat access without chat, folder, or sender selectors. No paid public-post search is used.
• Catalog reuse can delay folder membership changes; public-channel grants still use fresh metadata. Expired/partial catalogs do not grant access.
• The fixed 30-post response preserves all text while reducing the complete MCP result from 83,588 to 32,075 bytes (61.6%); tools/list falls from 110,590 to 77,653 bytes (29.8%).
• Selected-source live checks covered history, keyword/link/media searches, explicit messages, context, albums, and reconnect. Global search, catalog loads, forums, and authorization revocation were not live-tested. See the validation record for evidence and coverage limits.

v0.2.0

Added

• A foreground, bearer-authenticated local HTTP server at 127.0.0.1:8765/mcp.
• A connect STDIO proxy so several MCP clients can share one Telegram session, read policy, and process-local cursor store.
• --version, pinned installation examples, and configuration guides for Codex, Claude Desktop, Claude Code, Cursor, and VS Code.
• Package build checks, platform/Python compatibility checks, Trusted Publisher release automation, and reviewed dependency-update PRs.

Changed

• Session locking supports Windows as well as macOS and Linux.
• Local files use explicit UTF-8 handling; configuration errors identify invalid fields and sources without exposing their values.
• Interactive configuration preserves existing settings on Enter and explicitly prompts for allow_all_chats.
• The README focuses on installation and first use; detailed usage, configuration, troubleshooting, release instructions, and completed specifications have their own documents.

Compatibility

• telegram-mcp serve remains the standalone STDIO command. The same 14 tools and message schemas are available through both transports.
• Shared clients must run as one trusted local user. The HTTP process is started explicitly; connect never starts it or falls back to opening another session.
• Stop the session-owning process before local login, configuration, catalog, or status commands. Use MCP get_status while the server is running.
• Existing Telegram sessions and TOML read-policy settings remain usable.