@overpod/mcp-telegram 1.4.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" }] };
     }
@@ -419,9 +433,7 @@ server.tool("telegram-get-profile", "Get detailed profile info of a Telegram use
     }
 });
 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)"),
+    target: z.string().describe("Username (@group), link (t.me/group), or invite link (t.me/+xxx)"),
 }, async ({ target }) => {
     const err = await requireConnection();
     if (err)
@@ -443,6 +455,145 @@ server.tool("telegram-join-chat", "Join a Telegram group or channel by username
         };
     }
 });
+server.tool("telegram-send-reaction", "Send an emoji reaction to a message. Pass emoji to react, omit to remove reaction", {
+    chatId: z.string().describe("Chat ID or username"),
+    messageId: z.number().describe("Message ID to react to"),
+    emoji: z.string().optional().describe("Reaction emoji (e.g. 👍❤️🔥😂🎉). Omit to remove reaction"),
+}, async ({ chatId, messageId, emoji }) => {
+    const err = await requireConnection();
+    if (err)
+        return { content: [{ type: "text", text: err }] };
+    try {
+        await telegram.sendReaction(chatId, messageId, emoji);
+        const action = emoji ? `Reacted ${emoji} to` : "Removed reaction from";
+        return { content: [{ type: "text", text: `${action} message ${messageId} in ${chatId}` }] };
+    }
+    catch (e) {
+        return { content: [{ type: "text", text: `Reaction error: ${e.message}` }] };
+    }
+});
+server.tool("telegram-send-scheduled", "Send a scheduled message to a Telegram chat. The message will be delivered at the specified time by Telegram servers", {
+    chatId: z.string().describe("Chat ID or username (use 'me' or 'self' for Saved Messages)"),
+    text: z.string().describe("Message text"),
+    scheduleDate: z.number().describe("Unix timestamp when to send the message (must be in the future)"),
+    replyTo: z.number().optional().describe("Message ID to reply to"),
+    parseMode: z.enum(["md", "html"]).optional().describe("Message format: md (Markdown) or html"),
+}, async ({ chatId, text, scheduleDate, replyTo, parseMode }) => {
+    const err = await requireConnection();
+    if (err)
+        return { content: [{ type: "text", text: err }] };
+    // Resolve 'me'/'self' to Saved Messages
+    let target = chatId;
+    if (target === "me" || target === "self") {
+        try {
+            const me = await telegram.getMe();
+            target = me.id;
+        }
+        catch {
+            return { content: [{ type: "text", text: "Failed to resolve Saved Messages" }] };
+        }
+    }
+    try {
+        await telegram.sendScheduledMessage(target, text, scheduleDate, replyTo, parseMode);
+        const date = new Date(scheduleDate * 1000).toISOString();
+        return { content: [{ type: "text", text: `Message scheduled for ${date} in ${chatId}` }] };
+    }
+    catch (e) {
+        return { content: [{ type: "text", text: `Schedule error: ${e.message}` }] };
+    }
+});
+server.tool("telegram-create-poll", "Create a poll in a Telegram chat", {
+    chatId: z.string().describe("Chat ID or username"),
+    question: z.string().describe("Poll question"),
+    answers: z.array(z.string()).min(2).max(10).describe("Answer options (2-10)"),
+    multipleChoice: z.boolean().default(false).describe("Allow multiple answers"),
+    quiz: z.boolean().default(false).describe("Quiz mode (one correct answer)"),
+    correctAnswer: z.number().optional().describe("Index of correct answer (0-based, required for quiz mode)"),
+}, async ({ chatId, question, answers, multipleChoice, quiz, correctAnswer }) => {
+    const err = await requireConnection();
+    if (err)
+        return { content: [{ type: "text", text: err }] };
+    try {
+        const msgId = await telegram.createPoll(chatId, question, answers, { multipleChoice, quiz, correctAnswer });
+        return { content: [{ type: "text", text: `Poll created in ${chatId}${msgId ? ` (message #${msgId})` : ""}` }] };
+    }
+    catch (e) {
+        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;
@@ -119,6 +137,13 @@ export declare class TelegramService {
         photo: boolean;
         lastSeen?: string;
     }>;
+    sendReaction(chatId: string, messageId: number, emoji?: string): Promise<void>;
+    sendScheduledMessage(chatId: string, text: string, scheduleDate: number, replyTo?: number, parseMode?: "md" | "html"): Promise<void>;
+    createPoll(chatId: string, question: string, answers: string[], options?: {
+        multipleChoice?: boolean;
+        quiz?: boolean;
+        correctAnswer?: number;
+    }): Promise<number>;
     joinChat(target: string): Promise<{
         id: string;
         title: string;

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) {
@@ -603,6 +669,63 @@ export class TelegramService {
             lastSeen,
         };
     }
+    async sendReaction(chatId, messageId, emoji) {
+        if (!this.client || !this.connected)
+            throw new Error("Not connected");
+        const peer = await this.client.getInputEntity(chatId);
+        const reaction = emoji ? [new Api.ReactionEmoji({ emoticon: emoji })] : []; // empty = remove reaction
+        await this.client.invoke(new Api.messages.SendReaction({
+            peer,
+            msgId: messageId,
+            reaction,
+        }));
+    }
+    async sendScheduledMessage(chatId, text, scheduleDate, replyTo, parseMode) {
+        if (!this.client || !this.connected)
+            throw new Error("Not connected");
+        await this.client.sendMessage(chatId, {
+            message: text,
+            schedule: scheduleDate,
+            ...(replyTo ? { replyTo } : {}),
+            ...(parseMode ? { parseMode: parseMode === "html" ? "html" : "md" } : {}),
+        });
+    }
+    async createPoll(chatId, question, answers, options) {
+        if (!this.client || !this.connected)
+            throw new Error("Not connected");
+        const peer = await this.client.getInputEntity(chatId);
+        const pollAnswers = answers.map((text, i) => new Api.PollAnswer({
+            text: new Api.TextWithEntities({ text, entities: [] }),
+            option: Buffer.from([i]),
+        }));
+        const poll = new Api.Poll({
+            id: bigInt(Date.now()),
+            question: new Api.TextWithEntities({ text: question, entities: [] }),
+            answers: pollAnswers,
+            multipleChoice: options?.multipleChoice ?? false,
+            quiz: options?.quiz ?? false,
+        });
+        const result = await this.client.invoke(new Api.messages.SendMedia({
+            peer,
+            media: new Api.InputMediaPoll({
+                poll,
+                ...(options?.quiz && options.correctAnswer != null
+                    ? { correctAnswers: [Buffer.from([options.correctAnswer])] }
+                    : {}),
+            }),
+            message: "",
+            randomId: bigInt(Math.floor(Math.random() * 1e15)),
+        }));
+        // Extract message ID from result
+        if (result instanceof Api.Updates || result instanceof Api.UpdatesCombined) {
+            for (const update of result.updates) {
+                if (update instanceof Api.UpdateMessageID) {
+                    return update.id;
+                }
+            }
+        }
+        return 0;
+    }
     async joinChat(target) {
         if (!this.client)
             throw new Error("Not connected");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@overpod/mcp-telegram",
-  "version": "1.4.0",
-  "description": "MCP server for Telegram userbot — 20 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": {