@overpod/mcp-telegram 1.5.0 → 1.6.0

package/README.md

@@ -8,7 +8,7 @@
 [![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.
+> **Hosted version available!** Don't want to self-host? Use [mcp-telegram.com](https://mcp-telegram.com) -- connect Telegram to Claude.ai or ChatGPT 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">
@@ -20,11 +20,11 @@ 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
-- **21 tools** -- messaging, chat management, media, contacts, and more
+- **Full-featured** -- messaging, reactions, polls, scheduled messages, 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
-- **Works with any MCP client** -- Claude Code, Claude Desktop, Cursor, VS Code, Mastra, etc.
+- **Works with any MCP client** -- Claude Code, Claude Desktop, ChatGPT, Cursor, VS Code, Mastra, etc.
 
 ## Prerequisites
 
@@ -162,6 +162,9 @@ const telegramMcp = new MCPClient({
 |------|-------------|
 | `telegram-send-message` | Send a text message to a chat |
 | `telegram-send-file` | Send a file (photo, document, video, etc.) to a chat |
+| `telegram-send-reaction` | Send or remove an emoji reaction on a message |
+| `telegram-send-scheduled` | Schedule a message for future delivery |
+| `telegram-create-poll` | Create a poll (multiple choice or quiz mode) |
 | `telegram-edit-message` | Edit a previously sent message |
 | `telegram-delete-message` | Delete messages in a chat |
 | `telegram-forward-message` | Forward messages between chats |
@@ -284,6 +287,35 @@ Most tools accept `chatId` as a string -- either a numeric ID (e.g., `"-10012345
 |-----------|------|----------|-------------|
 | `target` | string | yes | Username (@group), link (t.me/group), or invite link (t.me/+xxx) |
 
+### telegram-send-reaction
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `chatId` | string | yes | Chat ID or @username |
+| `messageId` | number | yes | Message ID to react to |
+| `emoji` | string | no | Reaction emoji (e.g. 👍❤️🔥😂🎉). Omit to remove reaction |
+
+### telegram-send-scheduled
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `chatId` | string | yes | Chat ID or @username (use `"me"` or `"self"` for Saved Messages) |
+| `text` | string | yes | Message text |
+| `scheduleDate` | number | yes | Unix timestamp when to send (must be in the future) |
+| `replyTo` | number | no | Message ID to reply to |
+| `parseMode` | `"md"` / `"html"` | no | Message formatting mode |
+
+### telegram-create-poll
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `chatId` | string | yes | Chat ID or @username |
+| `question` | string | yes | Poll question |
+| `answers` | string[] | yes | Answer options (2-10 items) |
+| `multipleChoice` | boolean | no | Allow multiple answers (default: false) |
+| `quiz` | boolean | no | Quiz mode with one correct answer (default: false) |
+| `correctAnswer` | number | no | Index of correct answer, 0-based (required for quiz mode) |
+
 ### telegram-search-messages
 
 | Parameter | Type | Required | Description |
@@ -340,7 +372,7 @@ npm run format     # Format code with Biome
 
 ```
 src/
-  index.ts            -- MCP server entry point, 21 tool definitions
+  index.ts            -- MCP server entry point, tool definitions
   telegram-client.ts  -- TelegramService class (GramJS wrapper)
   qr-login-cli.ts     -- CLI utility for QR code login
 ```

package/dist/index.js

@@ -119,7 +119,10 @@ server.tool("telegram-send-message", "Send a message to a Telegram chat", {
 server.tool("telegram-list-chats", "List Telegram chats", {
     limit: z.number().default(20).describe("Number of chats to return"),
     offsetDate: z.number().optional().describe("Unix timestamp offset for pagination"),
-    filterType: z.enum(["private", "group", "channel"]).optional().describe("Filter by chat type"),
+    filterType: z
+        .enum(["private", "group", "channel", "contact_requests"])
+        .optional()
+        .describe("Filter by chat type. 'contact_requests' shows only private chats from non-contacts"),
 }, async ({ limit, offsetDate, filterType }) => {
     const err = await requireConnection();
     if (err)
@@ -127,7 +130,13 @@ server.tool("telegram-list-chats", "List Telegram chats", {
     try {
         const dialogs = await telegram.getDialogs(limit, offsetDate, filterType);
         const text = dialogs
-            .map((d) => `${d.type === "group" ? "G" : d.type === "channel" ? "C" : "P"} ${d.name} (${d.id}) ${d.unreadCount > 0 ? `[${d.unreadCount} unread]` : ""}`)
+            .map((d) => {
+            const prefix = d.type === "group" ? "G" : d.type === "channel" ? "C" : "P";
+            const botTag = d.isBot ? " [bot]" : "";
+            const contactTag = d.type === "private" && d.isContact === false ? " [not in contacts]" : "";
+            const unread = d.unreadCount > 0 ? ` [${d.unreadCount} unread]` : "";
+            return `${prefix} ${d.name} (${d.id})${botTag}${contactTag}${unread}`;
+        })
             .join("\n");
         return { content: [{ type: "text", text: text || "No chats" }] };
     }
@@ -204,7 +213,12 @@ server.tool("telegram-get-unread", "Get unread Telegram chats", {
     try {
         const dialogs = await telegram.getUnreadDialogs(limit);
         const text = dialogs
-            .map((d) => `${d.type === "group" ? "G" : d.type === "channel" ? "C" : "P"} ${d.name} (${d.id}) [${d.unreadCount} unread]`)
+            .map((d) => {
+            const prefix = d.type === "group" ? "G" : d.type === "channel" ? "C" : "P";
+            const botTag = d.isBot ? " [bot]" : "";
+            const contactTag = d.type === "private" && d.isContact === false ? " [not in contacts]" : "";
+            return `${prefix} ${d.name} (${d.id})${botTag}${contactTag} [${d.unreadCount} unread]`;
+        })
             .join("\n");
         return { content: [{ type: "text", text: text || "No unread chats" }] };
     }
@@ -507,6 +521,79 @@ server.tool("telegram-create-poll", "Create a poll in a Telegram chat", {
         return { content: [{ type: "text", text: `Poll error: ${e.message}` }] };
     }
 });
+server.tool("telegram-get-contact-requests", "Get incoming messages from non-contacts (contact requests). Shows who messaged you without being in your contacts, with message preview", {
+    limit: z.number().default(20).describe("Number of contact requests to return"),
+}, async ({ limit }) => {
+    const err = await requireConnection();
+    if (err)
+        return { content: [{ type: "text", text: err }] };
+    try {
+        const requests = await telegram.getContactRequests(limit);
+        if (requests.length === 0) {
+            return { content: [{ type: "text", text: "No contact requests" }] };
+        }
+        const text = requests
+            .map((r) => {
+            const tag = r.isBot ? "[bot]" : "[user]";
+            const username = r.username ? ` @${r.username}` : "";
+            const unread = r.unreadCount > 0 ? ` [${r.unreadCount} unread]` : "";
+            const preview = r.lastMessage ? `\n  > ${r.lastMessage.slice(0, 100)}` : "";
+            return `${tag} ${r.name}${username} (${r.id})${unread}${preview}`;
+        })
+            .join("\n");
+        return { content: [{ type: "text", text: text }] };
+    }
+    catch (e) {
+        return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+    }
+});
+server.tool("telegram-add-contact", "Add a user to your Telegram contacts. Use this to accept contact requests from non-contacts", {
+    userId: z.string().describe("User ID or username to add"),
+    firstName: z.string().describe("First name for the contact"),
+    lastName: z.string().optional().describe("Last name for the contact"),
+    phone: z.string().optional().describe("Phone number for the contact"),
+}, async ({ userId, firstName, lastName, phone }) => {
+    const err = await requireConnection();
+    if (err)
+        return { content: [{ type: "text", text: err }] };
+    try {
+        await telegram.addContact(userId, firstName, lastName, phone);
+        return {
+            content: [{ type: "text", text: `Contact added: ${firstName}${lastName ? ` ${lastName}` : ""} (${userId})` }],
+        };
+    }
+    catch (e) {
+        return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+    }
+});
+server.tool("telegram-block-user", "Block a Telegram user. Blocked users cannot send you messages", {
+    userId: z.string().describe("User ID or username to block"),
+}, async ({ userId }) => {
+    const err = await requireConnection();
+    if (err)
+        return { content: [{ type: "text", text: err }] };
+    try {
+        await telegram.blockUser(userId);
+        return { content: [{ type: "text", text: `User blocked: ${userId}` }] };
+    }
+    catch (e) {
+        return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+    }
+});
+server.tool("telegram-report-spam", "Report a chat as spam to Telegram", {
+    chatId: z.string().describe("Chat ID or username to report"),
+}, async ({ chatId }) => {
+    const err = await requireConnection();
+    if (err)
+        return { content: [{ type: "text", text: err }] };
+    try {
+        await telegram.reportSpam(chatId);
+        return { content: [{ type: "text", text: `Reported as spam: ${chatId}` }] };
+    }
+    catch (e) {
+        return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+    }
+});
 // --- Start ---
 async function main() {
     // Try to auto-connect with saved session

package/dist/telegram-client.d.ts

@@ -43,18 +43,34 @@ export declare class TelegramService {
     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<{
+    getDialogs(limit?: number, offsetDate?: number, filterType?: "private" | "group" | "channel" | "contact_requests"): Promise<Array<{
         id: string;
         name: string;
         type: string;
         unreadCount: number;
+        isBot?: boolean;
+        isContact?: boolean;
     }>>;
     getUnreadDialogs(limit?: number): Promise<Array<{
         id: string;
         name: string;
         type: string;
         unreadCount: number;
+        isBot?: boolean;
+        isContact?: boolean;
     }>>;
+    getContactRequests(limit?: number): Promise<Array<{
+        id: string;
+        name: string;
+        username?: string;
+        isBot: boolean;
+        unreadCount: number;
+        lastMessage?: string;
+        lastMessageDate?: number;
+    }>>;
+    addContact(userId: string, firstName: string, lastName?: string, phone?: string): Promise<void>;
+    blockUser(userId: string): Promise<void>;
+    reportSpam(chatId: string): Promise<void>;
     markAsRead(chatId: string): Promise<void>;
     forwardMessage(fromChatId: string, toChatId: string, messageIds: number[]): Promise<void>;
     editMessage(chatId: string, messageId: number, newText: string): Promise<void>;
@@ -66,6 +82,8 @@ export declare class TelegramService {
         username?: string;
         description?: string;
         membersCount?: number;
+        isBot?: boolean;
+        isContact?: boolean;
     }>;
     /** Extract media info from a message */
     private extractMediaInfo;

package/dist/telegram-client.js

@@ -309,12 +309,22 @@ export class TelegramService {
             throw new Error("Not connected");
         const fetchLimit = filterType ? limit * 3 : limit;
         const dialogs = await this.client.getDialogs({ limit: fetchLimit, ...(offsetDate ? { offsetDate } : {}) });
-        const mapped = dialogs.map((d) => ({
-            id: d.id?.toString() ?? "",
-            name: d.title ?? d.name ?? "Unknown",
-            type: d.isGroup ? "group" : d.isChannel ? "channel" : "private",
-            unreadCount: d.unreadCount,
-        }));
+        const mapped = dialogs.map((d) => {
+            const type = d.isGroup ? "group" : d.isChannel ? "channel" : "private";
+            const isUser = d.entity instanceof Api.User;
+            return {
+                id: d.id?.toString() ?? "",
+                name: d.title ?? d.name ?? "Unknown",
+                type,
+                unreadCount: d.unreadCount,
+                ...(isUser
+                    ? { isBot: Boolean(d.entity.bot), isContact: Boolean(d.entity.contact) }
+                    : {}),
+            };
+        });
+        if (filterType === "contact_requests") {
+            return mapped.filter((d) => d.type === "private" && d.isContact === false).slice(0, limit);
+        }
         return filterType ? mapped.filter((d) => d.type === filterType).slice(0, limit) : mapped;
     }
     async getUnreadDialogs(limit = 20) {
@@ -324,13 +334,67 @@ export class TelegramService {
         return dialogs
             .filter((d) => d.unreadCount > 0)
             .slice(0, limit)
-            .map((d) => ({
-            id: d.id?.toString() ?? "",
-            name: d.title ?? d.name ?? "Unknown",
-            type: d.isGroup ? "group" : d.isChannel ? "channel" : "private",
-            unreadCount: d.unreadCount,
+            .map((d) => {
+            const isUser = d.entity instanceof Api.User;
+            return {
+                id: d.id?.toString() ?? "",
+                name: d.title ?? d.name ?? "Unknown",
+                type: d.isGroup ? "group" : d.isChannel ? "channel" : "private",
+                unreadCount: d.unreadCount,
+                ...(isUser
+                    ? { isBot: Boolean(d.entity.bot), isContact: Boolean(d.entity.contact) }
+                    : {}),
+            };
+        });
+    }
+    async getContactRequests(limit = 20) {
+        if (!this.client || !this.connected)
+            throw new Error("Not connected");
+        const dialogs = await this.client.getDialogs({ limit: limit * 5 });
+        return dialogs
+            .filter((d) => {
+            if (d.isGroup || d.isChannel)
+                return false;
+            return d.entity instanceof Api.User && !d.entity.contact;
+        })
+            .slice(0, limit)
+            .map((d) => {
+            const user = d.entity;
+            const msg = d.message;
+            return {
+                id: d.id?.toString() ?? "",
+                name: [user.firstName, user.lastName].filter(Boolean).join(" ") || "Unknown",
+                username: user.username ?? undefined,
+                isBot: Boolean(user.bot),
+                unreadCount: d.unreadCount,
+                lastMessage: msg?.message ?? undefined,
+                lastMessageDate: msg?.date ?? undefined,
+            };
+        });
+    }
+    async addContact(userId, firstName, lastName, phone) {
+        if (!this.client || !this.connected)
+            throw new Error("Not connected");
+        const entity = await this.client.getInputEntity(userId);
+        await this.client.invoke(new Api.contacts.AddContact({
+            id: entity,
+            firstName,
+            lastName: lastName ?? "",
+            phone: phone ?? "",
         }));
     }
+    async blockUser(userId) {
+        if (!this.client || !this.connected)
+            throw new Error("Not connected");
+        const entity = await this.client.getInputEntity(userId);
+        await this.client.invoke(new Api.contacts.Block({ id: entity }));
+    }
+    async reportSpam(chatId) {
+        if (!this.client || !this.connected)
+            throw new Error("Not connected");
+        const peer = await this.client.getInputEntity(chatId);
+        await this.client.invoke(new Api.messages.ReportSpam({ peer }));
+    }
     async markAsRead(chatId) {
         if (!this.client || !this.connected)
             throw new Error("Not connected");
@@ -362,6 +426,8 @@ export class TelegramService {
                 name: parts.join(" ") || "Unknown",
                 type: "private",
                 username: entity.username ?? undefined,
+                isBot: Boolean(entity.bot),
+                isContact: Boolean(entity.contact),
             };
         }
         if (entity instanceof Api.Channel) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@overpod/mcp-telegram",
-  "version": "1.5.0",
-  "description": "MCP server for Telegram userbot — 24 tools for messages, media, contacts & more. Built on GramJS/MTProto.",
+  "version": "1.6.0",
+  "description": "MCP server for Telegram userbot — messages, media, reactions, polls & more. Built on GramJS/MTProto.",
   "type": "module",
   "main": "dist/index.js",
   "exports": {