@overpod/mcp-telegram 1.38.2 → 1.39.0

package/CHANGELOG.md

@@ -5,6 +5,13 @@ 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)
 
 

package/README.md

@@ -67,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

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.2",
+  "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",
@@ -35,7 +35,6 @@
     "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",
-    "gen:changelog:check": "tsx scripts/gen-changelog-docs.ts --check",
     "predocs:dev": "npm run gen:changelog",
     "docs:dev": "vitepress dev docs",
     "predocs:build": "npm run gen:changelog",