Telegram MCP Server v1.20.0

Telegram MCP Server 1.20.0

• MCP cancellation now stops local waits over STDIO and Streamable HTTP. A send already dispatched to Telegram remains recoverable through its receipt.
• TDLib client shutdown, uploads, and session cleanup are safer. Session clear keeps a private recovery copy by default and offers --no-backup.
• Optional numeric query arguments accept null as omission. Invalid integers and supplied null numeric mutation arguments are rejected.
• The JAR, app archives, and container images carry TDLight and native dependency licenses, notices, and source references.

Upgrading

• On Linux and macOS, a group- or world-writable session ancestor without the sticky bit can prevent startup. Check the named directory and follow the permission upgrade instructions.
• The default session-clear backup contains unencrypted session credentials. Use session clear --account <label> --yes --no-backup to skip the new copy. See session maintenance.

Verification and downloads

The release workflow passed the native matrix and built runtime archives for Windows x64, Linux x64 and ARM64, and macOS ARM64. The JAR and Windows ZIP were downloaded and checked against their published digests and notice files. The Linux x64 runtime and STDIO images are in GHCR. See the notice index and bundle guide.

What's Changed

• docs(release): record verified 1.19.1 publication by @berloga006 in #61
• docs: clarify release container signature evidence by @berloga006 in #62
• build(deps): Bump the actions group with 4 updates by @dependabot[bot] in #63
• Support MCP cancellation and harden TDLib lifecycle and session storage by @berloga006 in #64
• chore(release): prepare Telegram MCP Server 1.20.0 by @berloga006 in #65

Full Changelog: v1.19.1...v1.20.0

Telegram MCP Server v1.19.1

Fixed

A termination signal received during server startup could race with Spring Boot shutdown-hook registration, producing IllegalStateException: Shutdown in progress and a misleading Application run failed stack trace. Server termination now has one owner: the existing bounded ServerShutdown path. This fixes the race seen by the release STDIO smoke and adds deterministic regression coverage plus a six-delay signal sweep.

Companion skill and documentation

• Telegram Inbox Assistant 0.1.3 is included, with bounded, read-only guidance for optional resources/subscriptions and HTTP 413 recovery. Minimum compatible server remains 1.17.2.
• README now includes a real terminal recording and an architecture diagram. Publication and marketplace submission records are updated.

Upgrade

No configuration migration is required. The inventory remains 126 tools, and read-only defaults, account isolation and approval policies are unchanged from 1.19.0. Existing 1.19.0 assets and tags are not replaced.

Use the runtime-inclusive archive for Windows x64, Linux x64/ARM64 or Apple-silicon macOS; these include Java. The standalone JAR requires Java 25+. Checksums are in release-manifest.json; artifacts have GitHub provenance attestations and the container digests are signed.

Full changes: v1.19.0...v1.19.1

Telegram MCP Server v1.19.0

This release adds ten tools (116 to 126), opt-in MCP resources with subscriptions, and a round of security hardening. Spring Boot is 4.1.2 and Spring AI MCP is 2.0.2. The Inbox Assistant skill is unchanged (0.1.2).

Highlights

• New tools (116 → 126):
  • send_album, send_location, send_venue, send_contact and send_chat_action;
  • list_join_requests and process_join_request;
  • unpin_all_messages and delete_messages_by_sender, which are destructive and need confirmation;
  • get_chat_statistics, which returns summary statistics without graphs.
• MCP resources (opt-in):
  • telegram://{account}/chats, telegram://{account}/chat/{chatId} and telegram://{account}/chat/{chatId}/message/{messageId}.
  • A read runs the backing read tool, so profiles, read-only mode, account scopes, grants and chat allow-lists all apply.
  • Subscriptions send notifications/resources/updated. See docs/RESOURCES.md.
• Hardening: approval links, permission and secret-file checks, the input filter, and HTTP error codes. See the upgrade notes below.

Upgrade notes / behaviour changes

• Resources are off by default. Set MCP_RESOURCES_ENABLED=true to enable them. With resources on, these settings apply:

  Setting	Default	Effect
  MCP_RESOURCE_SUBSCRIPTIONS	true	Enables subscriptions
  MCP_RESOURCE_MAX_SUBSCRIPTIONS	50	Cap per session
  MCP_RESOURCE_DEBOUNCE	1s	Coalescing window per URI

  While subscriptions are active, /mcp POST bodies over 1 MiB (declared or chunked) are refused with HTTP 413.

• Destructive tools: server-mode.confirmation.destructive-tools now adds to the built-in destructive set instead of replacing it. A configured name that is not a write tool fails startup.

• High-risk writes need human approval when MCP_DESTRUCTIVE_APPROVAL is on, the same as destructive tools:

  • Built-in set: forward_message, send_file, promote_admin, demote_admin, set_privacy_settings, invite_to_group, update_profile, configure_chat_folder, unban_user, unblock_user and press_inline_button.
  • Plus any tools in server-mode.confirmation.high-risk-tools.
  • MCP_APPROVAL_SCOPE=destructive restores the 1.18.1 behaviour. all-writes gates every write.

• The loopback approval link is no longer written to stderr. The server opens it in the browser instead.

  • To print the link, set MCP_APPROVAL_LINK_ON_STDERR=true, or run with stderr attached to a terminal.
  • If neither is possible, the operation is refused instead of waiting.
  • The approval page accepts a decision only as a same-origin form POST that carries the page's form token. Forged requests get 403.

• Input filter: create_group titles, set_bot_commands descriptions and every outgoing text field of the new send tools go through MCP_GUARDRAILS_BLOCKEDPATTERNS and MCP_GUARDRAILS_MAXTOOLINPUTLENGTH.

• File checks:

  • MCP_PERMISSIONS_FILE must be a regular file, not a symlink, that other local users cannot write.
  • On Windows, secret, overrides and permissions files are checked by SID, and a parent folder that lets broad groups replace the file is rejected.
  • On POSIX, a parent directory that others can write without the sticky bit is rejected.

• HTTP status codes:

  • Unknown paths such as /mcp/ return 404 instead of 500.
  • A missing or wrong API key returns 401 with WWW-Authenticate: Bearer realm="telegram-mcp" instead of 403.

• server-mode.read-only defaults to true in code as well as in application.yml.

• send_album partial failures: if a send fails part-way, the outcome is reported as unknown and the album is not retried. Check the chat, or call get_send_operation if you set an idempotency_key, before sending again.

• Deployment fixes:

  • The safe-draft-reply recipe, which failed the 1.18.1 startup check, is fixed.
  • docker-compose.yml allows its own telegram-mcp Host and passes through the approval settings.
  • For reverse-proxy deployments upgrading from 1.18.0, see MCP_ALLOWED_HOSTS / MCP_ALLOWED_ORIGINS in docs/DEPLOYMENT_MODES.md.

• Dependencies:

  • Spring Boot 4.1.1 → 4.1.2 and Spring AI MCP 2.0.1 → 2.0.2.
  • The pinned gradle/actions/setup-gradle is now 6.4.1 and docker/login-action is 4.7.0 (#45, #46).

Changelog | Release readiness

What's Changed

• docs(release): record 1.18.1 publication and skill review receipt by @berloga006 in #48
• build(deps): Bump the kotlin-and-spring group across 1 directory with 3 updates by @dependabot[bot] in #45
• build(deps): Bump the actions group across 1 directory with 2 updates by @dependabot[bot] in #46
• fix(security): 1.18.2 hardening by @tolboy in #49
• feat: media and moderation tools (send_album, rich sends, join requests, chat statistics) by @tolboy in #50
• feat: opt-in MCP resources and resource subscriptions (roadmap stage 3) by @tolboy in #51
• docs(release): prepare 1.19.0 by @tolboy in #52

Full Changelog: v1.18.1...v1.19.0

Telegram MCP Server v1.18.1

This patch hardens MCP HTTP sessions, client grants, local session storage and anti-spam policies. The full inventory remains 116 tools. Inbox Assistant is 0.1.2 (minimum server 1.17.2).

Upgrade note

Write deployments must select MCP_DESTRUCTIVE_APPROVAL=auto, elicitation or loopback, or explicitly opt into previous behavior with MCP_ALLOW_MODEL_CONFIRMED_WRITES=true. Human approval covers destructive tools, not every mutation. Read-only defaults remain. Configure additional Origin/Host values for reverse proxies; clients reinitialize after session expiry returns 404.

Changes

• Behaviour change: MCP_READ_ONLY=false with MCP_DESTRUCTIVE_APPROVAL=off
  refuses to start. Destructive confirmation via "confirmed": true is an
  argument the model can set. Set auto, elicitation, or loopback, or
  opt in with MCP_ALLOW_MODEL_CONFIRMED_WRITES=true. Generated client config
  already sets approval when writes are enabled.
• Reject a present, non-loopback Origin on /mcp with HTTP 403 unless it is
  listed in MCP_ALLOWED_ORIGINS. Requests without Origin stay allowed.
• Cap in-flight tool calls per client with MCP_MAX_CONCURRENT_CALLS_PER_CLIENT
  (default 8). The account bulkhead is unchanged.
• Clamp runtime anti-spam overrides to a default ceiling, refuse a shared-write
  or corrupt overrides file at startup, and reject secret files that Everyone
  or Authenticated Users can write on Windows.
• Warn when a TDLib session directory is created, record that TDLib is not
  encrypting it, and restrict the directory to the owner on POSIX. Warn when
  HTTP is bound off loopback in API-key mode.
• Stop publishing the Actuator environment contributor and full git metadata
  on unauthenticated /actuator/info.
• Declare Gradle plugin versions in settings.gradle.kts so IntelliJ can
  resolve org.jetbrains.kotlin.gradle.dsl.JvmTarget. Reload the Gradle project
  after updating.
• Behaviour change: a present non-loopback Host on /mcp is HTTP 403
  unless it is listed in MCP_ALLOWED_HOSTS. A missing Host stays allowed.
  Mcp-Session-Id is bound to its authenticated owner when issued at initialize;
  another client's DELETE cannot remove ownership.
• TELEGRAM_MUTATION_CHAT_IDS narrows targets of chat-scoped write tools.
  Empty keeps the read allow-list. File operations cannot read or write a
  path that overlaps a TDLib session directory.
• Advertise the five recipe prompts. A prompt does not grant tools. A tool
  call with _meta.progressToken reports start and finish progress.
• When MCP_PERMISSIONS_FILE is set, the SDK filters tools/list and manifest
  entries by grants and accessible accounts, including asynchronous SSE and
  STDIO's stdio identity. HTTP authentication is propagated to SDK workers
  so execution, account scopes and client concurrency use the verified caller.
• Fill missing dimensions of partial anti-spam ceilings; prevent runtime
  overrides from redirecting counters or disabling deduplication. Reject empty
  policy files and Windows shared-write ALLOW entries, including BUILTIN Users.
• Apply POSIX TDLib directory protection during auth wizard login as well as
  startup. Warn about API-key HTTP exposure even when server.address is unset.
• Isolate conformance daemon cleanup from operator state and stream SSE without
  buffering; bound canary archive extraction. Update Inbox Assistant to 0.1.2
  locally with accurate error and pagination guidance.
• If Mcp-Method or Mcp-Name is present on POST /mcp, it must match the
  JSON-RPC body. Missing headers stay valid for current clients.
• Docker client config mounts the API hash file read-only instead of putting
  a hash placeholder in the environment. The auth wizard sends
  Referrer-Policy: no-referrer and a CSP nonce that is not the login nonce.

Validation and limits

Local review: 1042 JVM passed, 2 Windows symlink skips; 11 Python passed; independent STDIO/HTTP/bridge and live read-only baratnor checks passed, no messages sent. Tag CI gates the published artifacts. Six focused conformance checks succeeded, but Windows Node/libuv crashed; full conformance is not claimed.

Review evidence | Migration and readiness

Telegram MCP Server v1.18.0

Highlights

• Add wait_for_changes: wait for observed Telegram changes with resumable cursors, account/chat permissions and explicit coverage gaps.
• Read richer message context: outgoing status, edit time, album ID, forward origin and quoted replies, plus summaries for more content types.
• Upgrade TDLib to 1.8.68 and classify Telegram errors with actionable error codes, retry delays, bounded tool-call deadlines and per-account concurrency limits.
• Prevent unsafe retries after partial forwards or an earlier successful write. Keyed sends preserve uncertain outcomes instead of risking duplicates.
• Update MCP Java SDK to 2.1.0, Gradle to 9.8.2 and pinned GitHub Actions.

The full tool surface now contains 116 tools.

Upgrade notes

• Invalid HTML/Markdown now returns INVALID_INPUT before sending instead of posting raw markup.
• Handle Telegram-specific error codes and follow retryable / retry_after_seconds. For SEND_OUTCOME_UNKNOWN, inspect the chat or call get_send_operation before retrying.
• If overriding request timeouts, keep TDLIB_TOOL_DEADLINE longer than both TDLIB_REQUEST_TIMEOUT and TDLIB_MESSAGE_SEND_TIMEOUT.
• set_admin_rights replaces the complete rights set and rejects unknown keys. Read and preserve existing rights, including the new can_send_welcome_messages.
• mediaAlbumId is returned as a decimal string to preserve its full precision.

Runtime-inclusive archives are available for Windows x64, Linux x64/ARM64 and macOS ARM64, alongside the runnable JAR, SBOM, companion skill, optional bridge and package manifests.

Feature PRs: #42, #43. See CHANGELOG.md for the complete behavior changes.

Full changelog: v1.17.3...v1.18.0

Telegram MCP Server v1.17.3

Summary

Fixes: session clear now checks every TDLib lock file before clearing a session and moves the data aside in one atomic step, so an interrupted clear can't leave a half-deleted session. doctor now reports leftover staging folders (#27, #37).

Dependencies: Kotlin 2.4.21, Caffeine 3.3.1, Gradle wrapper 9.8.1, updated GitHub Actions (CodeQL 4.38.3 and others).

No configuration changes needed. Upgrading from 1.17.2 is a drop-in replacement.

What's Changed

• build(deps): Bump gradle-wrapper from 9.7.1 to 9.8.1 by @dependabot[bot] in #36
• build(deps): Bump the actions group across 1 directory with 9 updates by @dependabot[bot] in #30
• build(deps): Bump com.github.ben-manes.caffeine:caffeine from 3.2.4 to 3.3.1 by @dependabot[bot] in #35
• build(deps): Bump the kotlin-and-spring group across 1 directory with 2 updates by @dependabot[bot] in #22
• fix(session): probe every TDLib lock file and stage clear behind an atomic move by @tolboy in #37
• docs(release): prepare 1.17.3 by @tolboy in #38

Full Changelog: v1.17.2...v1.17.3

Telegram MCP Server v1.17.2

What's Changed

• fix(packaging): stabilize skill ZIP metadata across platforms by @berloga006 in #32
• docs(release): record published 1.17.1 verification by @berloga006 in #33
• fix(daemon): persist across Windows host exits and stabilize journal tests by @berloga006 in #34

Full Changelog: v1.17.1...v1.17.2

Telegram MCP Server v1.17.1

What's Changed

• fix(mcp): prepare 1.17.1 and read-only Agensi skill by @berloga006 in #31

Full Changelog: v1.17.0...v1.17.1

Telegram MCP Server v1.17.0

What's Changed

• feat: complete durable Telegram tasks, permissions and shared daemon by @tolboy in #26

Full Changelog: v1.16.2...v1.17.0

Telegram MCP Server v1.16.2

Security patch release: HTTP requests now use Spring CSRF protection, including loopback access. This prevents unauthenticated browser form submissions to local state-changing endpoints such as /auth/logout.

Compatibility

• API-key clients, OAuth Bearer clients, and the nonce-protected browser authentication wizard continue to work without an additional CSRF token.
• Direct HTTP scripts must send a configured API key even on localhost, or provide a valid CSRF token. Keyless state-changing requests without a valid CSRF token now return 403.
• STDIO is unaffected by this security change.

Other changes since v1.16.0

• Broadcast-channel reactions return aggregate counts when Telegram hides individual senders.
• Updated Spring Boot, Spring AI/MCP, Gradle, and pinned GitHub Actions. Kotlin remains at 2.4.0 for CodeQL compatibility.

See CHANGELOG.md and interactive-auth instructions.

Full changelog: v1.16.0...v1.16.2

The v1.16.1 tag did not publish artifacts because its old keyless HTTP smoke clients were rejected by the new CSRF protection. v1.16.2 authenticates those clients with a per-run key; all five platform smoke jobs pass.