@overpod/mcp-telegram 1.38.1 → 1.39.0

package/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.39.0](https://github.com/mcp-telegram/mcp-telegram/compare/v1.38.2...v1.39.0) (2026-06-21)
+
+
+### Added
+
+* complete QR login for accounts with 2FA ([#59](https://github.com/mcp-telegram/mcp-telegram/issues/59)) ([8b57965](https://github.com/mcp-telegram/mcp-telegram/commit/8b5796584edcc974d31b410db15fe1ee31ca84ca))
+
+## [1.38.2](https://github.com/mcp-telegram/mcp-telegram/compare/v1.38.1...v1.38.2) (2026-06-19)
+
+
+### Documentation
+
+* backfill v1.27–v1.28 in CHANGELOG; bump Pages actions off Node 20 ([#56](https://github.com/mcp-telegram/mcp-telegram/issues/56)) ([7786819](https://github.com/mcp-telegram/mcp-telegram/commit/778681917a2bc133ea8821e2ff8739a3f859b257))
+* generate changelog pages from CHANGELOG.md + refresh README ([#54](https://github.com/mcp-telegram/mcp-telegram/issues/54)) ([4422901](https://github.com/mcp-telegram/mcp-telegram/commit/442290178c5bee43cc6828f794ce468930cbe945))
+
 ## [1.38.1](https://github.com/mcp-telegram/mcp-telegram/compare/v1.38.0...v1.38.1) (2026-06-10)
 
 
@@ -350,6 +365,63 @@ Tests: 490/490 pass.
 - **Album mixed photo+video** — GramJS accepts mixed arrays via extension-based detection, but this is not covered by tests; recommend uniform media type per album until a live-test checkpoint confirms.
 - **Album flood control** — a 10-item album fans out 10 `messages.UploadMedia` calls inside one rate-limit slot; under heavy contention the later items may still hit `FLOOD_WAIT`. Rate limiter retries apply.
 
+## [1.28.1] - 2026-04-22
+
+### Added
+- **`telegram-logout`** — new tool (Auth category, annotated `DESTRUCTIVE`). Fully logs out: calls `auth.LogOut` on Telegram servers (session disappears from Settings → Devices), destroys the GramJS client, deletes the local session file, and clears in-memory state. Takes no parameters. Handles every state cleanly — connected (server revoke + local wipe), disconnected with a session file (local wipe only, with a notice), no session (`fail` "Not logged in"), and `auth.LogOut` throwing (local wipe still happens, with a "check Settings → Devices manually" hint).
+
+### Changed
+- **`TelegramService.logOut()` hardened** — server-revoke and client-destroy are now split: a successful `auth.LogOut` returns `true` even if `client.destroy()` throws (previously misreported "not confirmed"). The local wipe is verified post-unlink and throws if the session file survives (e.g. read-only Docker mount), instead of falsely reporting success. File removal now always runs even when server-revoke fails (network error, `AUTH_KEY_UNREGISTERED`).
+- **Master cancels active QR login on logout** — a `telegram-logout` request now aborts an in-progress QR login flow before acquiring `globalLock`, instead of queuing behind it for up to 5 minutes.
+
+### Testing
+- 322 unit tests (+10 vs v1.28.0) — `hasLocalSession()`, `logOut()` edge cases (connected / disconnected±file / network error / idempotency / FS-throws / destroy-throws-but-revoke-succeeds), and a Master integration test that logout aborts an active login over a real unix socket.
+
+### Notes & known limitations
+- In a 3-client FIFO scenario (A holds the lock via login, B queues a tool call, C requests logout), logout correctly aborts A, but B still runs before logout because FIFO order is preserved. A priority-aware queue is deferred.
+
+## [1.28.0] - 2026-04-22
+
+### Added
+- **QR login through the IPC daemon** — `mcp-telegram login` now flows through the Master daemon over IPC instead of running as a separate process. The new session reaches the Master's memory immediately, with no editor restart. This fixes the "relogin via `mcp-telegram login`" flavor of `AUTH_KEY_DUPLICATED`/`AUTH_KEY_UNREGISTERED`, where the standalone login wrote a fresh session to disk but the running Master kept the old, now-invalidated auth key in memory and then wiped the just-created session on the next tool call.
+  - `IpcClient.loginFlow(onQr)` — streams QR frames as they refresh (~every 10s).
+  - `handleLoginStart` on Master — runs `startQrLogin` on the shared `TelegramService`.
+  - `GlobalLock` (FIFO mutex) — serializes tool calls with the login flow so other clients queue instead of hitting a stale client mid-relogin.
+  - `AbortController` — `socket.on("close")` aborts the QR loop if the CLI is interrupted (Ctrl+C / terminal closed); `globalLock` releases immediately instead of blocking tool calls for up to 5 minutes.
+  - Session swap now saves to disk first, then adopts in memory and destroys the previous client — prevents orphan Telegram connections accumulating per relogin.
+  - Standalone fallback kept — if no Master is running, `mcp-telegram login` works exactly as before.
+
+### Changed
+- **BREAKING (internal IPC only): IPC protocol is now a discriminated union** with a required `type` tag (`tool` / `tool_response` / `login_start` / `login_qr` / `login_done`). A new 1.28.0 client and an older 1.27.x Master cannot talk — restart your editor / Claude Code after upgrading so the Master daemon is replaced. No public API or invocation change. (Parent-crash detection already kills stale Masters in most cases, so this is transparent for VS Code / Claude Desktop users.)
+
+### Fixed
+- Socket errors on Master now log to stderr instead of being silently dropped.
+- `client.destroy()` in abort branches wrapped in try/catch — guarantees the "QR login aborted" message even if Telegram destroy throws.
+- QR render errors (`QRCode.toString` failure) logged to stderr instead of silently dropped.
+
+### Testing
+- 312 unit tests (was 288) — new suites for `GlobalLock` (FIFO ordering, double-release safety), Master login (QR URL forwarding, abort on socket close), child-process integration via tsx, `IpcClient.loginFlow`, and IPC discriminated-union / legacy-protocol rejection.
+
+## [1.27.1] - 2026-04-22
+
+### Changed
+- Patch release — no new tools, no API changes; pure code-quality and test-coverage work. Refactored `telegram-client.ts` re-exports (eliminates 2 Biome `noUnusedImports` false-positives), replaced unsafe `(e as Error).message` casts with `e instanceof Error` guards in the stats methods, and added `McpRegisteredTool` / `McpServerInternal` types to `ipc-protocol.ts` as a single source of truth (previously duplicated across master.ts and client.ts).
+
+### Testing
+- 286 unit tests (+25 vs v1.27.0) — new branch coverage for `wireIpcProxies` (incl. a safety test that the original `TelegramService` handler is never called after wiring), the rate limiter (`throwOnFloodWait`, retry exhaustion, 5xx, GramJS `errorMessage`), and the IPC protocol parser (malformed JSON, blank lines, partial-line buffering, multiple messages per chunk). `rate-limiter.ts` reached 100% statements.
+
+## [1.27.0] - 2026-04-21
+
+### Added
+- **Master/Client IPC daemon — fixes `AUTH_KEY_DUPLICATED` across concurrent Claude sessions.** Opening multiple Claude sessions used to spawn separate `mcp-telegram` processes that each connected to Telegram with the same session, which Telegram rejected as a duplicate. Now the first process to start becomes the **Master** (holds the single GramJS connection, listens on a Unix socket at `~/.mcp-telegram/daemon.sock`) and every subsequent process becomes a thin **Client** that proxies tool calls to the Master over the socket — one connection, one auth key, no duplicates. Zero config change; same invocation.
+  - New files: `src/lock.ts` (atomic `O_EXCL` PID lockfile + stale-lock detection via `kill -0`), `src/ipc-protocol.ts` (IPC message types + newline-delimited JSON parser), `src/master.ts` (Unix socket server, sequential queue dispatcher), `src/client.ts` (`IpcClient` with timeout + retry, handler proxy).
+  - Security: socket file is `chmod 0o600` (owner-only); the session string never leaves the Master process.
+
+### Fixed
+- Atomic lock via `O_EXCL` prevents a race when multiple sessions start simultaneously; stale socket from a previous crash is removed before `listen` (no `EADDRINUSE`).
+- One-shot connect timeout (not idle) so live connections survive inactivity; 30s IPC call timeout so a stuck Master surfaces a clean error instead of hanging.
+- Sequential `drainQueue()` loop for correct concurrent-request handling; `.catch()` on auto-connect to avoid `unhandledRejection`; idempotent cleanup (`cleanedUp` flag) so SIGINT/SIGTERM don't double-release.
+
 ## [1.26.0] - 2026-04-20
 
 ### Added

package/README.md

@@ -4,7 +4,7 @@
 [![npm downloads](https://img.shields.io/npm/dm/@overpod/mcp-telegram)](https://www.npmjs.com/package/@overpod/mcp-telegram)
 [![Node.js](https://img.shields.io/badge/Node.js-18%2B-339933.svg?logo=node.js&logoColor=white)](https://nodejs.org/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-6.0-blue.svg?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
-[![MCP SDK](https://img.shields.io/badge/MCP%20SDK-1.27-green.svg)](https://modelcontextprotocol.io/)
+[![MCP SDK](https://img.shields.io/badge/MCP%20SDK-1.29-green.svg)](https://modelcontextprotocol.io/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![mcp-telegram MCP server](https://glama.ai/mcp/servers/overpod/mcp-telegram/badges/score.svg)](https://glama.ai/mcp/servers/overpod/mcp-telegram)
 
@@ -18,13 +18,15 @@ An MCP (Model Context Protocol) server that connects AI assistants like Claude t
 
 ## Features
 
-- **Comprehensive tool coverage** -- the most full-featured Telegram MCP server available (80+ tools)
+- **Comprehensive tool coverage** -- the most full-featured Telegram MCP server available
 - **MTProto protocol** -- direct Telegram API access, not the limited Bot API
 - **Userbot** -- operates as your personal account, not a bot
 - **Full-featured** -- messaging, reactions, polls, scheduled messages, stickers, media, contacts, and more
 - **Forum Topics** -- list topics, read per-topic messages, send to specific topics, per-topic unread counts
 - **Stickers** -- search sticker sets, browse installed/recent stickers, send stickers to any chat
 - **Account & profile management** -- update profile, set emoji status, birthday, personal channel, profile photo, manage privacy settings, sessions, auto-delete timers
+- **Chat folders** -- create, edit, delete and reorder folders, toggle folder tags, read suggested folders (v1.33.0)
+- **Global privacy** -- read and set account-wide privacy settings (v1.33.0)
 - **Global search** -- search messages across all chats at once
 - **Real-time polling** -- fetch updates via stateless cursors; agent owns `{pts, qts, date}` state
 - **Inline bots & buttons** -- query inline bots, send results, press callback buttons
@@ -34,6 +36,8 @@ An MCP (Model Context Protocol) server that connects AI assistants like Claude t
 - **Admin controls** -- toggle channel signatures, anti-spam, forum mode, prehistory; approve join requests
 - **Stats** -- channel and supergroup analytics (GetBroadcastStats / GetMegagroupStats)
 - **Boosts & Business** -- boost status, boosters list, Telegram Business chat links CRUD, work hours, location, greeting/away/intro messages
+- **Star gifts** -- browse available and saved gifts, save/convert gifts, manage Stars balance and subscriptions (opt-in via `MCP_TELEGRAM_ENABLE_STARS=1`, v1.34.0)
+- **Shared daemon** -- one background process serves multiple MCP clients over a single Telegram session; see the [shared-daemon guide](https://mcp-telegram.github.io/mcp-telegram/guides/shared-daemon) (v1.38.0)
 - **QR code login** -- authenticate by scanning a QR code in the Telegram app
 - **Session persistence** -- login once, stay connected across restarts
 - **Human-readable output** -- sender names are resolved, not just numeric IDs
@@ -63,6 +67,14 @@ A QR code will appear in the terminal. Open Telegram on your phone, go to **Sett
 
 > **Custom session path:** set `TELEGRAM_SESSION_PATH=/path/to/session` to store the session file elsewhere.
 
+> **Two-step verification (2FA):** if your account has a cloud password enabled, scanning the QR code is not enough — Telegram also requires the password. Provide it via `TELEGRAM_2FA_PASSWORD` so the login can complete:
+>
+> ```bash
+> TELEGRAM_API_ID=YOUR_ID TELEGRAM_API_HASH=YOUR_HASH TELEGRAM_2FA_PASSWORD=YOUR_PASSWORD npx @overpod/mcp-telegram login
+> ```
+>
+> The password is only used locally to answer Telegram's SRP challenge and is never persisted.
+
 ### 3. Add to Claude
 
 ```bash
@@ -363,6 +375,8 @@ All tools are auto-discoverable via MCP — your AI client will see the full lis
 | **Rich Media Sending** | `telegram-send-voice`, `telegram-send-video-note` (round video), `telegram-send-location` (static or live), `telegram-send-venue`, `telegram-send-contact`, `telegram-send-dice` (🎲🎯🎰🏀⚽🎳), `telegram-send-album` (2–10 grouped photos/videos) |
 | **Groups** | `telegram-create-group`, `telegram-edit-group`, `telegram-invite-to-group`, `telegram-join-chat`, `telegram-leave-group`, `telegram-kick-user`, `telegram-ban-user`, `telegram-unban-user`, `telegram-set-admin`, `telegram-remove-admin`, `telegram-get-my-role`, `telegram-set-chat-permissions`, `telegram-set-slow-mode`, `telegram-get-admin-log` |
 | **Chat Info** | `telegram-get-chat-info`, `telegram-get-chat-members`, `telegram-get-chat-folders` |
+| **Folders (v1.33.0)** | `telegram-create-folder`, `telegram-edit-folder`, `telegram-delete-folder`, `telegram-reorder-folders`, `telegram-get-suggested-folders`, `telegram-toggle-folder-tags` |
+| **Global Privacy (v1.33.0)** | `telegram-get-global-privacy-settings`, `telegram-set-global-privacy-settings` |
 | **Invite Links** | `telegram-create-invite-link`, `telegram-get-invite-links`, `telegram-revoke-invite-link` |
 | **Contacts** | `telegram-get-contacts`, `telegram-add-contact`, `telegram-get-contact-requests` |
 | **Moderation** | `telegram-block-user`, `telegram-unblock-user`, `telegram-report-spam` |
@@ -381,7 +395,7 @@ All tools are auto-discoverable via MCP — your AI client will see the full lis
 | **Read Receipts (v1.30.0)** | `telegram-get-message-read-participants`, `telegram-get-outbox-read-date` |
 | **Boosts** | `telegram-get-my-boosts`, `telegram-get-boosts-status`, `telegram-get-boosts-list` |
 | **Business (v1.32.0)** | `telegram-get-business-chat-links`, `telegram-create-business-chat-link`, `telegram-edit-business-chat-link`, `telegram-delete-business-chat-link`, `telegram-resolve-business-chat-link`, `telegram-set-business-hours`, `telegram-set-business-location`, `telegram-set-business-greeting`, `telegram-set-business-away`, `telegram-set-business-intro` |
-| **Opt-in (env-gated)** | `telegram-get-group-call`, `telegram-get-group-call-participants` (requires `MCP_TELEGRAM_ENABLE_GROUP_CALLS=1`), `telegram-get-stars-status`, `telegram-get-stars-transactions` (requires `MCP_TELEGRAM_ENABLE_STARS=1`), `telegram-get-quick-replies`, `telegram-get-quick-reply-messages` (requires `MCP_TELEGRAM_ENABLE_QUICK_REPLIES=1`) |
+| **Opt-in (env-gated)** | `telegram-get-group-call`, `telegram-get-group-call-participants` (requires `MCP_TELEGRAM_ENABLE_GROUP_CALLS=1`); Stars & gifts `telegram-get-stars-status`, `telegram-get-stars-transactions`, `telegram-get-stars-topup-options`, `telegram-get-stars-subscriptions`, `telegram-change-stars-subscription`, `telegram-get-available-star-gifts`, `telegram-get-saved-star-gifts`, `telegram-save-star-gift`, `telegram-convert-star-gift` (requires `MCP_TELEGRAM_ENABLE_STARS=1`); `telegram-get-quick-replies`, `telegram-get-quick-reply-messages` (requires `MCP_TELEGRAM_ENABLE_QUICK_REPLIES=1`) |
 
 > **Tip**: Ask your AI assistant *"What Telegram tools are available?"* to get the full list with parameters and descriptions.
 
@@ -392,7 +406,7 @@ Some tools are disabled by default and must be opted in via environment variable
 | Variable | Value | Tools enabled |
 |----------|-------|---------------|
 | `MCP_TELEGRAM_ENABLE_GROUP_CALLS` | `1` | `telegram-get-group-call`, `telegram-get-group-call-participants` |
-| `MCP_TELEGRAM_ENABLE_STARS` | `1` | `telegram-get-stars-status`, `telegram-get-stars-transactions` |
+| `MCP_TELEGRAM_ENABLE_STARS` | `1` | Stars balance & transactions, top-up options, subscriptions, and Star Gifts (browse / save / convert) |
 | `MCP_TELEGRAM_ENABLE_QUICK_REPLIES` | `1` | `telegram-get-quick-replies`, `telegram-get-quick-reply-messages` |
 
 Add these to your `.env` file or MCP client config to enable them.

package/dist/telegram-client.d.ts

@@ -3,6 +3,30 @@ import { Api } from "telegram/tl/index.js";
 import type { AllStoriesSummary, BoostsListSummary, BoostsStatusSummary, BroadcastStatsSummary, BusinessChatLinksSummary, ChannelDifferenceSummary, ChatPermissions, DiscussionMessageSummary, EmojiStatusSummary, GroupCallParticipantsSummary, GroupCallSummary, GroupsForDiscussionSummary, MegagroupStatsSummary, MessageButtonDescriptor, MyBoostsSummary, PeerStoriesSummary, PollSummary, QuickRepliesSummary, QuickReplyMessagesSummary, ReadParticipantsSummary, ReportResultSummary, ResolvedBusinessChatLinkSummary, StarsStatusSummary, StoriesByIdSummary, StoryPrivacy, StoryViewsListSummary, UpdatesDifferenceSummary } from "./telegram-helpers.js";
 export type { AllStoriesSummary, BoostSummary, BoostsListSummary, BoostsStatusSummary, BroadcastStatsSummary, BusinessChatLinkSummary, BusinessChatLinksSummary, ChannelDifferenceSummary, ChatPermissions, CompactPeer, CompactStatsGraph, DiscussionMessageSummary, EmojiStatusSummary, GroupCallInfoSummary, GroupCallParticipantSummary, GroupCallParticipantsSummary, GroupCallSummary, GroupsForDiscussionSummary, MegagroupStatsSummary, MessageButtonDescriptor, MyBoostSummary, MyBoostsSummary, PeerStoriesSummary, PeerSummary, PollSummary, PrepaidGiveawaySummary, QuickRepliesSummary, QuickReplyMessageSummary, QuickReplyMessagesSummary, QuickReplySummary, ReadParticipantsSummary, ReportResultSummary, ResolvedBusinessChatLinkSummary, StarsAmountSummary, StarsStatusSummary, StarsSubscriptionPricingSummary, StarsSubscriptionSummary, StarsTransactionPeerSummary, StarsTransactionSummary, StatsValue, StoriesByIdSummary, StoryItemSummary, StoryPrivacy, StoryViewSummary, StoryViewsListSummary, UpdatesDifferenceSummary, UpdatesMessageSummary, } from "./telegram-helpers.js";
 export { buildStoryPrivacyRules, describeAdminLogAction, describeAdminLogDetails, describeKeyboardButton, detectMediaType, extractPeerId, extractPollMediaFromUpdates, extractStoryIdFromUpdates, mergeBannedRights, peerToCompact, reactionToEmoji, summarizeAllStories, summarizeBoost, summarizeBoostsList, summarizeBoostsStatus, summarizeBroadcastStats, summarizeBusinessChatLink, summarizeBusinessChatLinks, summarizeChannelDifference, summarizeDiscussionMessage, summarizeEmojiStatus, summarizeGroupCall, summarizeGroupCallInfo, summarizeGroupCallParticipant, summarizeGroupCallParticipants, summarizeGroupsForDiscussion, summarizeMegagroupStats, summarizeMyBoost, summarizeMyBoosts, summarizePeer, summarizePeerStories, summarizePoll, summarizePrepaidGiveaway, summarizeQuickReplies, summarizeQuickReply, summarizeQuickReplyMessage, summarizeQuickReplyMessages, summarizeReadParticipants, summarizeReportResult, summarizeStarsAmount, summarizeStarsStatus, summarizeStarsSubscription, summarizeStarsTransaction, summarizeStarsTransactionPeer, summarizeStoriesById, summarizeStoryItem, summarizeStoryView, summarizeStoryViewsList, summarizeUpdatesDifference, } from "./telegram-helpers.js";
+/** Minimal client surface the 2FA SRP step needs — lets us unit-test the
+ *  branch logic with a stub instead of a live TelegramClient. */
+interface SrpClient {
+    invoke(request: unknown): Promise<unknown>;
+}
+/** The SRP digest function (GetPassword response + plaintext → InputCheckPasswordSRP).
+ *  Injectable so tests can exercise the orchestration without GramJS's real crypto. */
+type ComputeCheckFn = (request: Api.account.Password, password: string) => Promise<Api.TypeInputCheckPasswordSRP>;
+/**
+ * Complete a QR login that Telegram answered with SESSION_PASSWORD_NEEDED by
+ * running the SRP cloud-password check: GetPassword → computeCheck → CheckPassword.
+ *
+ * Returns a discriminated outcome rather than throwing so the caller owns
+ * connection teardown. The password is only used to answer the SRP challenge
+ * and is never logged or persisted.
+ *
+ * `compute` is injectable for tests; production always uses GramJS `computeCheck`.
+ */
+export declare function completeTwoFactorLogin(client: SrpClient, password: string | undefined, compute?: ComputeCheckFn): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+}>;
 export type ChatEntity = Api.User | Api.Chat | Api.Channel | Api.TypeUser | Api.TypeChat;
 export declare class TelegramService {
     private client;

package/dist/telegram-client.js

@@ -7,6 +7,7 @@ import bigInt from "big-integer";
 import QRCode from "qrcode";
 import { TelegramClient } from "telegram";
 import { CustomFile } from "telegram/client/uploads.js";
+import { computeCheck } from "telegram/Password.js";
 import { StringSession } from "telegram/sessions/index.js";
 import { Api } from "telegram/tl/index.js";
 import { RateLimiter } from "./rate-limiter.js";
@@ -22,6 +23,46 @@ const NOT_CONNECTED_ERROR = "Not connected. Run telegram-status to check or tele
 function resolveSessionPath(sessionPath) {
     return sessionPath ?? process.env.TELEGRAM_SESSION_PATH ?? DEFAULT_SESSION_FILE;
 }
+// Cloud password (2FA) for accounts that have two-step verification enabled.
+// QR login alone cannot complete such logins — Telegram answers the imported
+// login token with SESSION_PASSWORD_NEEDED, after which an SRP password check
+// is required. Supplied via env so it works across all login entry points
+// (standalone CLI, daemon IPC, and the telegram-login MCP tool), none of which
+// can reliably prompt interactively mid-flow.
+function resolveTwoFactorPassword() {
+    return process.env.TELEGRAM_2FA_PASSWORD || undefined;
+}
+/**
+ * Complete a QR login that Telegram answered with SESSION_PASSWORD_NEEDED by
+ * running the SRP cloud-password check: GetPassword → computeCheck → CheckPassword.
+ *
+ * Returns a discriminated outcome rather than throwing so the caller owns
+ * connection teardown. The password is only used to answer the SRP challenge
+ * and is never logged or persisted.
+ *
+ * `compute` is injectable for tests; production always uses GramJS `computeCheck`.
+ */
+export async function completeTwoFactorLogin(client, password, compute = computeCheck) {
+    if (!password) {
+        return {
+            ok: false,
+            message: "2FA is enabled on this account. Set TELEGRAM_2FA_PASSWORD to your cloud password and run login again.",
+        };
+    }
+    try {
+        const passwordInfo = (await client.invoke(new Api.account.GetPassword()));
+        const check = await compute(passwordInfo, password);
+        await client.invoke(new Api.auth.CheckPassword({ password: check }));
+        return { ok: true };
+    }
+    catch (pwErr) {
+        const reason = pwErr instanceof Error ? pwErr.message : String(pwErr);
+        return {
+            ok: false,
+            message: `2FA password check failed: ${reason}. Verify TELEGRAM_2FA_PASSWORD is correct.`,
+        };
+    }
+}
 function resolveProxy() {
     const ip = process.env.TELEGRAM_PROXY_IP;
     const port = process.env.TELEGRAM_PROXY_PORT;
@@ -318,8 +359,22 @@ export class TelegramService {
                 catch (err) {
                     const error = err;
                     if (error.errorMessage === "SESSION_PASSWORD_NEEDED") {
-                        await client.disconnect();
-                        return { success: false, message: "2FA enabled — QR login not supported with 2FA" };
+                        // The QR was scanned, but the account has two-step verification.
+                        // Complete the login with an SRP password check if we have the
+                        // cloud password; otherwise tell the user how to provide it.
+                        const outcome = await completeTwoFactorLogin(client, resolveTwoFactorPassword());
+                        if (outcome.ok) {
+                            resolved = true;
+                            break;
+                        }
+                        // destroy() (not disconnect()) to free the auth_key/socket, matching
+                        // every other failure exit in this method — important in daemon mode
+                        // where the process lives on across logins.
+                        try {
+                            await client.destroy();
+                        }
+                        catch { }
+                        return { success: false, message: outcome.message };
                     }
                 }
                 if (!resolved) {

package/dist/tools/auth.js

@@ -50,6 +50,8 @@ export function registerAuthTools(server, telegram) {
             `If the QR image is not visible, it's also saved to: ${qrFilePath}`,
             "",
             "After scanning, run **telegram-status** to verify the connection.",
+            "",
+            "If the account has two-step verification (2FA), set the `TELEGRAM_2FA_PASSWORD` environment variable to the cloud password and log in again — scanning alone cannot complete a 2FA login.",
         ].join("\n");
         return {
             content: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@overpod/mcp-telegram",
-  "version": "1.38.1",
+  "version": "1.39.0",
   "description": "MCP server for Telegram userbot — messages, media, reactions, polls & more. Built on GramJS/MTProto.",
   "type": "module",
   "main": "dist/index.js",
@@ -34,7 +34,10 @@
     "test": "tsx --test 'src/**/*.test.ts'",
     "test:watch": "tsx --test --watch 'src/**/*.test.ts'",
     "test:coverage": "c8 --all --src src --exclude 'src/**/*.test.ts' --reporter=text tsx --test 'src/**/*.test.ts'",
+    "gen:changelog": "tsx scripts/gen-changelog-docs.ts",
+    "predocs:dev": "npm run gen:changelog",
     "docs:dev": "vitepress dev docs",
+    "predocs:build": "npm run gen:changelog",
     "docs:build": "vitepress build docs",
     "docs:preview": "vitepress preview docs"
   },
@@ -68,12 +71,12 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.16",
-    "@types/node": "^25.9.2",
+    "@biomejs/biome": "^2.5.0",
+    "@types/node": "^25.9.3",
     "@types/qrcode": "^1.5.6",
     "c8": "^11.0.0",
     "tsx": "^4.22.4",
     "typescript": "^6.0.3",
-    "vitepress": "^1.6.4"
+    "vitepress": "^2.0.0-alpha.17"
   }
 }