@overpod/mcp-telegram 1.1.1 → 1.4.0

package/README.md

@@ -1,9 +1,18 @@
 # MCP Telegram
 
 [![npm](https://img.shields.io/npm/v/@overpod/mcp-telegram)](https://www.npmjs.com/package/@overpod/mcp-telegram)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)
+[![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-5.9-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/)
 [![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)
+
+> **Hosted version available!** Don't want to self-host? Use [mcp-telegram.com](https://mcp-telegram.com) -- connect Telegram to Claude.ai in 30 seconds with QR code. No API keys needed.
+
+<p align="center">
+  <img src="assets/demo.gif" alt="MCP Telegram demo — connect and summarize chats in Claude" width="700">
+</p>
 
 An MCP (Model Context Protocol) server that connects AI assistants like Claude to Telegram via the MTProto protocol. Unlike bots, this runs as a **userbot** -- it operates under your personal Telegram account using [GramJS](https://github.com/nicedoc/gramjs), giving full access to your chats, contacts, and message history.
 
@@ -11,7 +20,7 @@ An MCP (Model Context Protocol) server that connects AI assistants like Claude t
 
 - **MTProto protocol** -- direct Telegram API access, not the limited Bot API
 - **Userbot** -- operates as your personal account, not a bot
-- **20 tools** -- messaging, chat management, media, contacts, and more
+- **21 tools** -- messaging, chat management, media, contacts, and more
 - **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
@@ -174,6 +183,7 @@ const telegramMcp = new MCPClient({
 | `telegram-mark-as-read` | Mark a chat as read |
 | `telegram-get-chat-info` | Get detailed info about a chat (name, type, members count, description) |
 | `telegram-get-chat-members` | List members of a group or channel |
+| `telegram-join-chat` | Join a group or channel by username or invite link |
 | `telegram-pin-message` | Pin a message in a chat |
 | `telegram-unpin-message` | Unpin a message in a chat |
 
@@ -268,6 +278,12 @@ Most tools accept `chatId` as a string -- either a numeric ID (e.g., `"-10012345
 | `messageId` | number | yes | Message ID to pin |
 | `silent` | boolean | no | Pin without notification (default: false) |
 
+### telegram-join-chat
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `target` | string | yes | Username (@group), link (t.me/group), or invite link (t.me/+xxx) |
+
 ### telegram-search-messages
 
 | Parameter | Type | Required | Description |
@@ -324,7 +340,7 @@ npm run format     # Format code with Biome
 
 ```
 src/
-  index.ts            -- MCP server entry point, 20 tool definitions
+  index.ts            -- MCP server entry point, 21 tool definitions
   telegram-client.ts  -- TelegramService class (GramJS wrapper)
   qr-login-cli.ts     -- CLI utility for QR code login
 ```

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "dotenv/config";

package/dist/index.js

@@ -418,6 +418,31 @@ server.tool("telegram-get-profile", "Get detailed profile info of a Telegram use
         return { content: [{ type: "text", text: `Error: ${e.message}` }] };
     }
 });
+server.tool("telegram-join-chat", "Join a Telegram group or channel by username or invite link", {
+    target: z
+        .string()
+        .describe("Username (@group), link (t.me/group), or invite link (t.me/+xxx)"),
+}, async ({ target }) => {
+    const err = await requireConnection();
+    if (err)
+        return { content: [{ type: "text", text: err }] };
+    try {
+        const result = await telegram.joinChat(target);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Joined ${result.type}: ${result.title} (ID: ${result.id})`,
+                },
+            ],
+        };
+    }
+    catch (e) {
+        return {
+            content: [{ type: "text", text: `Error: ${e.message}` }],
+        };
+    }
+});
 // --- Start ---
 async function main() {
     // Try to auto-connect with saved session

package/dist/qr-login-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "dotenv/config";

package/dist/qr-login-cli.js

@@ -1,13 +1,7 @@
 #!/usr/bin/env node
 import "dotenv/config";
-import { exec } from "node:child_process";
-import { writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
 import QRCode from "qrcode";
 import { TelegramService } from "./telegram-client.js";
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const QR_IMAGE_PATH = join(__dirname, "..", "qr-login.png");
 const API_ID = Number(process.env.TELEGRAM_API_ID);
 const API_HASH = process.env.TELEGRAM_API_HASH;
 if (!API_ID || !API_HASH) {
@@ -15,10 +9,6 @@ if (!API_ID || !API_HASH) {
     process.exit(1);
 }
 const telegram = new TelegramService(API_ID, API_HASH);
-function openFile(path) {
-    const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
-    exec(`${cmd} "${path}"`);
-}
 async function main() {
     // Check if already connected
     await telegram.loadSession();
@@ -31,16 +21,7 @@ async function main() {
     console.log("\nStarting Telegram QR login...\n");
     console.log("Scan the QR code in Telegram app:");
     console.log("  Settings > Devices > Link Desktop Device\n");
-    const result = await telegram.startQrLogin(
-    // onQrDataUrl — save as PNG and open
-    async (dataUrl) => {
-        const base64 = dataUrl.replace(/^data:image\/png;base64,/, "");
-        await writeFile(QR_IMAGE_PATH, Buffer.from(base64, "base64"));
-        console.log(`QR saved: ${QR_IMAGE_PATH}`);
-        openFile(QR_IMAGE_PATH);
-    }, 
-    // onQrUrl — also show in terminal
-    async (url) => {
+    const result = await telegram.startQrLogin(() => { }, async (url) => {
         const terminalQr = await QRCode.toString(url, { type: "terminal", small: true });
         console.log(terminalQr);
         console.log("Waiting for scan...\n");

package/dist/telegram-client.d.ts

@@ -0,0 +1,127 @@
+export declare class TelegramService {
+    private client;
+    private apiId;
+    private apiHash;
+    private sessionString;
+    private connected;
+    lastError: string;
+    constructor(apiId: number, apiHash: string);
+    loadSession(): Promise<boolean>;
+    /** Set session string in memory (for programmatic / hosted use) */
+    setSessionString(session: string): void;
+    /** Get the current session string (for external persistence) */
+    getSessionString(): string;
+    private saveSession;
+    connect(): Promise<boolean>;
+    clearSession(): Promise<void>;
+    /** Ensure connection is active, auto-reconnect if session exists */
+    ensureConnected(): Promise<boolean>;
+    disconnect(): Promise<void>;
+    /**
+     * Log out from Telegram completely — terminates the session on Telegram servers.
+     * After this, the session string becomes invalid and won't appear in "Active Sessions".
+     */
+    logOut(): Promise<boolean>;
+    isConnected(): boolean;
+    startQrLogin(onQrDataUrl: (dataUrl: string) => void, onQrUrl?: (url: string) => void): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    getMe(): Promise<{
+        id: string;
+        username?: string;
+        firstName?: string;
+    }>;
+    sendMessage(chatId: string, text: string, replyTo?: number, parseMode?: "md" | "html"): Promise<void>;
+    sendFile(chatId: string, filePath: string, caption?: string): Promise<void>;
+    downloadMedia(chatId: string, messageId: number, downloadPath: string): Promise<string>;
+    downloadMediaAsBuffer(chatId: string, messageId: number): Promise<{
+        buffer: Buffer;
+        mimeType: string;
+    }>;
+    /** Detect MIME type from buffer magic bytes, falling back to media metadata */
+    private detectMimeType;
+    pinMessage(chatId: string, messageId: number, silent?: boolean): Promise<void>;
+    unpinMessage(chatId: string, messageId: number): Promise<void>;
+    getDialogs(limit?: number, offsetDate?: number, filterType?: "private" | "group" | "channel"): Promise<Array<{
+        id: string;
+        name: string;
+        type: string;
+        unreadCount: number;
+    }>>;
+    getUnreadDialogs(limit?: number): Promise<Array<{
+        id: string;
+        name: string;
+        type: string;
+        unreadCount: number;
+    }>>;
+    markAsRead(chatId: string): Promise<void>;
+    forwardMessage(fromChatId: string, toChatId: string, messageIds: number[]): Promise<void>;
+    editMessage(chatId: string, messageId: number, newText: string): Promise<void>;
+    deleteMessages(chatId: string, messageIds: number[]): Promise<void>;
+    getChatInfo(chatId: string): Promise<{
+        id: string;
+        name: string;
+        type: string;
+        username?: string;
+        description?: string;
+        membersCount?: number;
+    }>;
+    /** Extract media info from a message */
+    private extractMediaInfo;
+    /** Resolve sender ID to a display name */
+    private resolveSenderName;
+    getMessages(chatId: string, limit?: number, offsetId?: number, minDate?: number, maxDate?: number): Promise<Array<{
+        id: number;
+        text: string;
+        sender: string;
+        date: string;
+        media?: {
+            type: string;
+            fileName?: string;
+            size?: number;
+        };
+    }>>;
+    searchChats(query: string, limit?: number): Promise<Array<{
+        id: string;
+        name: string;
+        type: string;
+        username?: string;
+    }>>;
+    searchMessages(chatId: string, query: string, limit?: number, minDate?: number, maxDate?: number): Promise<Array<{
+        id: number;
+        text: string;
+        sender: string;
+        date: string;
+        media?: {
+            type: string;
+            fileName?: string;
+            size?: number;
+        };
+    }>>;
+    getContacts(limit?: number): Promise<Array<{
+        id: string;
+        name: string;
+        username?: string;
+        phone?: string;
+    }>>;
+    getChatMembers(chatId: string, limit?: number): Promise<Array<{
+        id: string;
+        name: string;
+        username?: string;
+    }>>;
+    getProfile(userId: string): Promise<{
+        id: string;
+        name: string;
+        username?: string;
+        phone?: string;
+        bio?: string;
+        photo: boolean;
+        lastSeen?: string;
+    }>;
+    joinChat(target: string): Promise<{
+        id: string;
+        title: string;
+        type: string;
+    }>;
+}

package/dist/telegram-client.js

@@ -27,9 +27,22 @@ export class TelegramService {
         }
         return false;
     }
+    /** Set session string in memory (for programmatic / hosted use) */
+    setSessionString(session) {
+        this.sessionString = session;
+    }
+    /** Get the current session string (for external persistence) */
+    getSessionString() {
+        return this.sessionString;
+    }
     async saveSession(session) {
         this.sessionString = session;
-        await writeFile(SESSION_FILE, session, "utf-8");
+        try {
+            await writeFile(SESSION_FILE, session, "utf-8");
+        }
+        catch {
+            // File write may fail in containerized environments — session string is still in memory
+        }
     }
     async connect() {
         if (this.connected && this.client)
@@ -96,11 +109,32 @@ export class TelegramService {
     }
     async disconnect() {
         if (this.client && this.connected) {
-            await this.client.disconnect();
+            await this.client.destroy();
             this.connected = false;
             this.client = null;
         }
     }
+    /**
+     * Log out from Telegram completely — terminates the session on Telegram servers.
+     * After this, the session string becomes invalid and won't appear in "Active Sessions".
+     */
+    async logOut() {
+        if (!this.client || !this.connected)
+            return false;
+        try {
+            await this.client.invoke(new Api.auth.LogOut());
+            await this.client.destroy();
+            this.connected = false;
+            this.sessionString = "";
+            this.client = null;
+            return true;
+        }
+        catch (error) {
+            console.error("[telegram] logOut error:", error);
+            await this.disconnect();
+            return false;
+        }
+    }
     isConnected() {
         return this.connected;
     }
@@ -166,19 +200,20 @@ export class TelegramService {
             }
             if (resolved) {
                 const newSession = client.session.save();
-                await client.disconnect();
-                await this.saveSession(newSession);
-                // Reconnect with new session
+                // Adopt the QR login client directly instead of destroy+reconnect
+                // This avoids creating a second Telegram session from DC migration auth keys
+                this.client = client;
                 this.sessionString = newSession;
-                await this.connect();
+                this.connected = true;
+                await this.saveSession(newSession);
                 return { success: true, message: "Telegram login successful" };
             }
-            await client.disconnect();
+            await client.destroy();
             return { success: false, message: "QR login timeout" };
         }
         catch (err) {
             try {
-                await client.disconnect();
+                await client.destroy();
             }
             catch { }
             return { success: false, message: `Login failed: ${err.message}` };
@@ -224,6 +259,41 @@ export class TelegramService {
         await writeFile(downloadPath, buffer);
         return downloadPath;
     }
+    async downloadMediaAsBuffer(chatId, messageId) {
+        if (!this.client || !this.connected)
+            throw new Error("Not connected");
+        const messages = await this.client.getMessages(chatId, { ids: [messageId] });
+        const message = messages[0];
+        if (!message)
+            throw new Error(`Message ${messageId} not found`);
+        if (!message.media)
+            throw new Error(`Message ${messageId} has no media`);
+        const buffer = (await this.client.downloadMedia(message));
+        if (!buffer)
+            throw new Error("Failed to download media");
+        const mimeType = this.detectMimeType(buffer, message.media);
+        return { buffer, mimeType };
+    }
+    /** Detect MIME type from buffer magic bytes, falling back to media metadata */
+    detectMimeType(buffer, media) {
+        // Check magic bytes first
+        if (buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff)
+            return "image/jpeg";
+        if (buffer[0] === 0x89 && buffer[1] === 0x50 && buffer[2] === 0x4e && buffer[3] === 0x47)
+            return "image/png";
+        if (buffer[0] === 0x47 && buffer[1] === 0x49 && buffer[2] === 0x46)
+            return "image/gif";
+        if (buffer[0] === 0x52 && buffer[1] === 0x49 && buffer[2] === 0x46 && buffer[3] === 0x46)
+            return "image/webp";
+        // Fall back to document mimeType
+        const m = media;
+        const doc = m.document;
+        if (doc?.mimeType)
+            return doc.mimeType;
+        if (m.photo)
+            return "image/jpeg";
+        return "application/octet-stream";
+    }
     async pinMessage(chatId, messageId, silent = false) {
         if (!this.client || !this.connected)
             throw new Error("Not connected");
@@ -295,20 +365,48 @@ export class TelegramService {
             };
         }
         if (entity instanceof Api.Channel) {
+            let membersCount = entity.participantsCount ?? undefined;
+            let description;
+            try {
+                const full = await this.client.invoke(new Api.channels.GetFullChannel({ channel: entity }));
+                if (full.fullChat instanceof Api.ChannelFull) {
+                    membersCount = membersCount ?? full.fullChat.participantsCount ?? undefined;
+                    description = full.fullChat.about || undefined;
+                }
+            }
+            catch {
+                // May fail for some channels — fall back to basic info
+            }
             return {
                 id: entity.id.toString(),
                 name: entity.title,
                 type: entity.megagroup ? "group" : "channel",
                 username: entity.username ?? undefined,
-                membersCount: entity.participantsCount ?? undefined,
+                description,
+                membersCount,
             };
         }
         if (entity instanceof Api.Chat) {
+            let membersCount = entity.participantsCount ?? undefined;
+            let description;
+            try {
+                const full = await this.client.invoke(new Api.messages.GetFullChat({ chatId: entity.id }));
+                if (full.fullChat instanceof Api.ChatFull) {
+                    if (!membersCount && full.fullChat.participants instanceof Api.ChatParticipants) {
+                        membersCount = full.fullChat.participants.participants.length;
+                    }
+                    description = full.fullChat.about || undefined;
+                }
+            }
+            catch {
+                // Fall back to basic info
+            }
             return {
                 id: entity.id.toString(),
                 name: entity.title,
                 type: "group",
-                membersCount: entity.participantsCount ?? undefined,
+                description,
+                membersCount,
             };
         }
         return { id: chatId, name: "Unknown", type: "unknown" };
@@ -505,4 +603,35 @@ export class TelegramService {
             lastSeen,
         };
     }
+    async joinChat(target) {
+        if (!this.client)
+            throw new Error("Not connected");
+        // Extract invite hash from various link formats
+        const inviteMatch = target.match(/(?:t\.me\/\+|t\.me\/joinchat\/|tg:\/\/join\?invite=)([a-zA-Z0-9_-]+)/);
+        if (inviteMatch) {
+            const result = await this.client.invoke(new Api.messages.ImportChatInvite({ hash: inviteMatch[1] }));
+            const chat = result.chats?.[0];
+            if (!chat)
+                throw new Error("Failed to join via invite link");
+            return {
+                id: chat.id.toString(),
+                title: chat.title ?? "Unknown",
+                type: chat.className === "Channel" ? "channel" : "group",
+            };
+        }
+        // Public channel/group by username
+        const username = target.replace(/^@/, "").replace(/^https?:\/\/t\.me\//, "");
+        const entity = await this.client.getEntity(username);
+        if (entity instanceof Api.Channel || entity instanceof Api.Chat) {
+            await this.client.invoke(new Api.channels.JoinChannel({
+                channel: entity,
+            }));
+            return {
+                id: entity.id.toString(),
+                title: entity.title ?? "Unknown",
+                type: entity.className === "Channel" ? "channel" : "group",
+            };
+        }
+        throw new Error("Target is not a group or channel. Use username, @username, or invite link.");
+    }
 }

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@overpod/mcp-telegram",
-  "version": "1.1.1",
+  "version": "1.4.0",
   "description": "MCP server for Telegram userbot — 20 tools for messages, media, contacts & more. Built on GramJS/MTProto.",
   "type": "module",
   "main": "dist/index.js",
+  "exports": {
+    ".": "./dist/index.js",
+    "./service": "./dist/telegram-client.js"
+  },
   "bin": {
     "mcp-telegram": "dist/cli.js"
   },
@@ -17,6 +21,7 @@
     "start": "node dist/index.js",
     "login": "node dist/qr-login-cli.js",
     "build": "tsc",
+    "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run build",
     "lint": "biome check src/",
     "lint:fix": "biome check --fix src/",