@overpod/mcp-telegram 1.38.2 → 1.39.1

package/CHANGELOG.md

@@ -5,6 +5,20 @@ 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.1](https://github.com/mcp-telegram/mcp-telegram/compare/v1.39.0...v1.39.1) (2026-06-21)
+
+
+### Fixed
+
+* **resolve:** recover bare numeric peer IDs that lack access_hash ([#62](https://github.com/mcp-telegram/mcp-telegram/issues/62)) ([678077a](https://github.com/mcp-telegram/mcp-telegram/commit/678077a78ce3a5852e07d5d831f664c3e08a81e3))
+
+## [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;
@@ -252,6 +276,13 @@ export declare class TelegramService {
      * Handles display names by searching dialogs.
      */
     private resolvePeer;
+    /**
+     * Resolve a bare numeric ID to a cached/dialog entity so GramJS can build a
+     * valid InputPeer. Falls back to the raw ID string if no dialog matches —
+     * GramJS may still resolve it (e.g. a contact or a peer it has messaged),
+     * and we must not regress that path.
+     */
+    private resolveNumericPeer;
     getChatInfo(chatId: string): Promise<{
         id: string;
         name: string;

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) {
@@ -1136,12 +1191,78 @@ export class TelegramService {
         // Normalize '@me' — GramJS only intercepts the plain 'me' string as InputPeerSelf
         if (chatId === "@me")
             return "me";
-        // Numeric IDs and @usernames work directly
-        if (/^-?\d+$/.test(chatId) || chatId.startsWith("@"))
+        // @usernames resolve directly via contacts.ResolveUsername
+        if (chatId.startsWith("@"))
             return chatId;
-        // Everything else — resolve via dialogs
+        // Bare numeric IDs need an entity with access_hash. GramJS can build an
+        // InputPeer from a raw number only if it's already cached or the account
+        // is a contact / has messaged us — otherwise getInputEntity throws
+        // "Could not find the input entity". A bare positive number is also
+        // ambiguous (GramJS assumes PeerUser, so channel IDs fail outright).
+        // Recover by looking the ID up among dialogs, which yields a full entity
+        // (with access_hash) for both users and channels.
+        if (/^-?\d+$/.test(chatId))
+            return this.resolveNumericPeer(chatId);
+        // Everything else — resolve display name via dialogs
         return this.resolveChat(chatId);
     }
+    /**
+     * Resolve a bare numeric ID to a cached/dialog entity so GramJS can build a
+     * valid InputPeer. Falls back to the raw ID string if no dialog matches —
+     * GramJS may still resolve it (e.g. a contact or a peer it has messaged),
+     * and we must not regress that path.
+     */
+    async resolveNumericPeer(chatId) {
+        if (!this.client)
+            throw new Error(NOT_CONNECTED_ERROR);
+        const cached = this.entityCache.get(chatId);
+        if (cached)
+            return cached;
+        // Direct resolve first — succeeds when GramJS already knows the peer.
+        try {
+            const entity = await this.client.getEntity(chatId);
+            this.entityCache.set(chatId, entity);
+            return entity;
+        }
+        catch {
+            // Fall through to dialog scan.
+        }
+        // Scan dialogs for a matching entity. IDs reach us in two shapes:
+        //   • bare positive  (e.g. 1004294063929 for a channel, 8959122940 for a
+        //     user) — this is what list-chats/search emit and what GramJS can't
+        //     disambiguate; match it against any entity's bare id.
+        //   • marked         (-100<id> for channels, -<id> for basic groups) — the
+        //     sign/-100 prefix carries the type, so require the entity to match that
+        //     exact marked form, otherwise a group "-123" could wrongly match a user
+        //     with bare id 123.
+        const isMarked = chatId.startsWith("-");
+        try {
+            const dialogs = await this.client.getDialogs({ limit: 100 });
+            const match = dialogs.find((d) => {
+                const entity = d.entity;
+                if (!entity?.id)
+                    return false;
+                const bare = entity.id.toString();
+                if (!isMarked)
+                    return chatId === bare;
+                // Marked input must match the entity's marked form.
+                if (entity instanceof Api.Channel)
+                    return chatId === `-100${bare}`;
+                if (entity instanceof Api.Chat)
+                    return chatId === `-${bare}`;
+                return false;
+            });
+            if (match?.entity) {
+                this.entityCache.set(chatId, match.entity);
+                return match.entity;
+            }
+        }
+        catch {
+            // Dialog fetch failed — fall back to the raw ID below.
+        }
+        // Last resort: hand the raw ID to GramJS and let it try GetUsers/GetChannels.
+        return chatId;
+    }
     async getChatInfo(chatId) {
         if (!this.client || !this.connected)
             throw new Error(NOT_CONNECTED_ERROR);

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.1",
   "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",
@@ -73,7 +72,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.0",
-    "@types/node": "^25.9.3",
+    "@types/node": "^26.0.0",
     "@types/qrcode": "^1.5.6",
     "c8": "^11.0.0",
     "tsx": "^4.22.4",