@overpod/mcp-telegram 1.7.0 → 1.8.0

package/README.md

@@ -21,6 +21,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
 - **Full-featured** -- messaging, reactions, polls, scheduled messages, media, contacts, and more
+- **Forum Topics** -- list topics, read per-topic messages, send to specific topics, per-topic unread counts
 - **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
@@ -46,7 +47,9 @@ An MCP (Model Context Protocol) server that connects AI assistants like Claude t
 TELEGRAM_API_ID=YOUR_ID TELEGRAM_API_HASH=YOUR_HASH npx @overpod/mcp-telegram login
 ```
 
-A QR code will appear in the terminal. Open Telegram on your phone, go to **Settings > Devices > Link Desktop Device**, and scan the code. The session is saved to `~/.telegram-session` and reused automatically.
+A QR code will appear in the terminal. Open Telegram on your phone, go to **Settings > Devices > Link Desktop Device**, and scan the code. The session is saved to `~/.mcp-telegram/session` and reused automatically.
+
+> **Custom session path:** set `TELEGRAM_SESSION_PATH=/path/to/session` to store the session file elsewhere.
 
 ### 3. Add to Claude
 
@@ -59,6 +62,34 @@ claude mcp add telegram -s user \
 
 That's it! Ask Claude to run `telegram-status` to verify.
 
+### Multiple Accounts
+
+Use `TELEGRAM_SESSION_PATH` to run separate Telegram accounts side by side:
+
+```bash
+# Login each account with a unique session path
+TELEGRAM_API_ID=ID1 TELEGRAM_API_HASH=HASH1 TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-work npx @overpod/mcp-telegram login
+TELEGRAM_API_ID=ID2 TELEGRAM_API_HASH=HASH2 TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-personal npx @overpod/mcp-telegram login
+```
+
+Then add each as a separate MCP server:
+
+```bash
+claude mcp add telegram-work -s user \
+  -e TELEGRAM_API_ID=ID1 \
+  -e TELEGRAM_API_HASH=HASH1 \
+  -e TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-work \
+  -- npx @overpod/mcp-telegram
+
+claude mcp add telegram-personal -s user \
+  -e TELEGRAM_API_ID=ID2 \
+  -e TELEGRAM_API_HASH=HASH2 \
+  -e TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-personal \
+  -- npx @overpod/mcp-telegram
+```
+
+Each account gets its own session file — no conflicts.
+
 ## Installation Options
 
 ### npx (recommended, zero install)
@@ -177,9 +208,16 @@ const telegramMcp = new MCPClient({
 | `telegram-read-messages` | Read recent messages from a chat |
 | `telegram-search-chats` | Search for chats, users, or channels by name |
 | `telegram-search-messages` | Search messages in a chat by text |
-| `telegram-get-unread` | Get chats with unread messages, bot/contact markers |
+| `telegram-get-unread` | Get chats with unread messages; forums show per-topic unread breakdown |
 | `telegram-get-contact-requests` | Get incoming messages from non-contacts with preview |
 
+### Forum Topics
+
+| Tool | Description |
+|------|-------------|
+| `telegram-list-topics` | List forum topics in a group with unread counts and status |
+| `telegram-read-topic-messages` | Read messages from a specific forum topic |
+
 ### Chat Management
 
 | Tool | Description |
@@ -226,6 +264,23 @@ Most tools accept `chatId` as a string -- either a numeric ID (e.g., `"-10012345
 | `text` | string | yes | Message text |
 | `replyTo` | number | no | Message ID to reply to |
 | `parseMode` | `"md"` / `"html"` | no | Message formatting mode |
+| `topicId` | number | no | Forum topic ID to send into (for groups with Topics) |
+
+### telegram-list-topics
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `chatId` | string | yes | Chat ID or @username (group with Topics enabled) |
+| `limit` | number | no | Max topics to return (default: 100) |
+
+### telegram-read-topic-messages
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `chatId` | string | yes | Chat ID or @username |
+| `topicId` | number | yes | Topic ID (from `telegram-list-topics`) |
+| `limit` | number | no | Number of messages (default: 20) |
+| `offsetId` | number | no | Message ID for pagination |
 
 ### telegram-list-chats
 
@@ -426,7 +481,8 @@ src/
 ## Security
 
 - API credentials are stored in `.env` (gitignored)
-- Session is stored in `.telegram-session` (gitignored)
+- Session is stored in `~/.mcp-telegram/session` with `0600` permissions (owner-only access)
+- Session directory is created with `0700` permissions
 - Phone number is **not required** -- QR-only authentication
 - This is a **userbot** (personal account), not a bot -- respect the [Telegram Terms of Service](https://core.telegram.org/api/terms)
 

package/dist/index.js

@@ -104,13 +104,15 @@ server.tool("telegram-send-message", "Send a message to a Telegram chat", {
     text: z.string().describe("Message text"),
     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, replyTo, parseMode }) => {
+    topicId: z.number().optional().describe("Forum topic ID to send message into (for groups with Topics enabled)"),
+}, async ({ chatId, text, replyTo, parseMode, topicId }) => {
     const err = await requireConnection();
     if (err)
         return { content: [{ type: "text", text: err }] };
     try {
-        await telegram.sendMessage(chatId, text, replyTo, parseMode);
-        return { content: [{ type: "text", text: `Message sent to ${chatId}` }] };
+        await telegram.sendMessage(chatId, text, replyTo, parseMode, topicId);
+        const dest = topicId ? `topic ${topicId} in ${chatId}` : chatId;
+        return { content: [{ type: "text", text: `Message sent to ${dest}` }] };
     }
     catch (e) {
         return { content: [{ type: "text", text: `Send error: ${e.message}` }] };
@@ -217,7 +219,13 @@ server.tool("telegram-get-unread", "Get unread Telegram chats", {
             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]`;
+            const forumTag = d.forum ? " [forum]" : "";
+            let line = `${prefix} ${d.name} (${d.id})${botTag}${contactTag}${forumTag} [${d.unreadCount} unread]`;
+            if (d.topics && d.topics.length > 0) {
+                const topicLines = d.topics.map((t) => `  # ${t.title} [${t.unreadCount} unread]`);
+                line += `\n${topicLines.join("\n")}`;
+            }
+            return line;
         })
             .join("\n");
         return { content: [{ type: "text", text: text || "No unread chats" }] };
@@ -303,6 +311,7 @@ server.tool("telegram-get-chat-info", "Get detailed info about a Telegram chat",
             `Name: ${info.name}`,
             `ID: ${info.id}`,
             `Type: ${info.type}`,
+            ...(info.forum ? ["Forum: yes"] : []),
             ...(info.username ? [`Username: @${info.username}`] : []),
             ...(info.description ? [`Description: ${info.description}`] : []),
             ...(info.membersCount != null ? [`Members: ${info.membersCount}`] : []),
@@ -594,6 +603,49 @@ server.tool("telegram-report-spam", "Report a chat as spam to Telegram", {
         return { content: [{ type: "text", text: `Error: ${e.message}` }] };
     }
 });
+server.tool("telegram-list-topics", "List forum topics in a Telegram group with Topics enabled. Shows topic names, unread counts, and status", {
+    chatId: z.string().describe("Chat ID or username of a group with Topics enabled"),
+    limit: z.number().default(100).describe("Max topics to return"),
+}, async ({ chatId, limit }) => {
+    const err = await requireConnection();
+    if (err)
+        return { content: [{ type: "text", text: err }] };
+    try {
+        const topics = await telegram.getForumTopics(chatId, limit);
+        const text = topics
+            .map((t) => {
+            const flags = [t.pinned ? "pinned" : "", t.closed ? "closed" : ""].filter(Boolean).join(", ");
+            const flagStr = flags ? ` [${flags}]` : "";
+            const unread = t.unreadCount > 0 ? ` [${t.unreadCount} unread]` : "";
+            return `# ${t.title} (id: ${t.id})${flagStr}${unread}`;
+        })
+            .join("\n");
+        return { content: [{ type: "text", text: text || "No topics found" }] };
+    }
+    catch (e) {
+        return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+    }
+});
+server.tool("telegram-read-topic-messages", "Read messages from a specific forum topic in a Telegram group", {
+    chatId: z.string().describe("Chat ID or username"),
+    topicId: z.number().describe("Topic ID (get from telegram-list-topics)"),
+    limit: z.number().default(20).describe("Number of messages to return"),
+    offsetId: z.number().optional().describe("Message ID to start from (for pagination)"),
+}, async ({ chatId, topicId, limit, offsetId }) => {
+    const err = await requireConnection();
+    if (err)
+        return { content: [{ type: "text", text: err }] };
+    try {
+        const messages = await telegram.getTopicMessages(chatId, topicId, limit, offsetId);
+        const text = messages
+            .map((m) => `[${m.date}] ${m.sender}: ${m.text}${m.media ? ` [${m.media.type}${m.media.fileName ? `: ${m.media.fileName}` : ""}]` : ""}`)
+            .join("\n\n");
+        return { content: [{ type: "text", text: text || "No messages in this topic" }] };
+    }
+    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

@@ -36,7 +36,7 @@ export declare class TelegramService {
         username?: string;
         firstName?: string;
     }>;
-    sendMessage(chatId: string, text: string, replyTo?: number, parseMode?: "md" | "html"): Promise<void>;
+    sendMessage(chatId: string, text: string, replyTo?: number, parseMode?: "md" | "html", topicId?: number): 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<{
@@ -62,6 +62,12 @@ export declare class TelegramService {
         unreadCount: number;
         isBot?: boolean;
         isContact?: boolean;
+        forum?: boolean;
+        topics?: Array<{
+            id: number;
+            title: string;
+            unreadCount: number;
+        }>;
     }>>;
     getContactRequests(limit?: number): Promise<Array<{
         id: string;
@@ -88,6 +94,7 @@ export declare class TelegramService {
         membersCount?: number;
         isBot?: boolean;
         isContact?: boolean;
+        forum?: boolean;
     }>;
     /** Extract media info from a message */
     private extractMediaInfo;
@@ -148,6 +155,28 @@ export declare class TelegramService {
         quiz?: boolean;
         correctAnswer?: number;
     }): Promise<number>;
+    getForumTopics(chatId: string, limit?: number): Promise<Array<{
+        id: number;
+        title: string;
+        unreadCount: number;
+        unreadMentions: number;
+        iconColor: number;
+        closed: boolean;
+        pinned: boolean;
+    }>>;
+    getTopicMessages(chatId: string, topicId: number, limit?: number, offsetId?: number): Promise<Array<{
+        id: number;
+        text: string;
+        sender: string;
+        date: string;
+        media?: {
+            type: string;
+            fileName?: string;
+            size?: number;
+        };
+    }>>;
+    /** Check if a chat entity is a forum (has topics enabled) */
+    isForum(chatId: string): Promise<boolean>;
     joinChat(target: string): Promise<{
         id: string;
         title: string;

package/dist/telegram-client.js

@@ -273,14 +273,29 @@ export class TelegramService {
             firstName: user.firstName ?? undefined,
         };
     }
-    async sendMessage(chatId, text, replyTo, parseMode) {
+    async sendMessage(chatId, text, replyTo, parseMode, topicId) {
         if (!this.client || !this.connected)
             throw new Error("Not connected");
-        await this.client.sendMessage(chatId, {
-            message: text,
-            ...(replyTo ? { replyTo } : {}),
-            ...(parseMode ? { parseMode: parseMode === "html" ? "html" : "md" } : {}),
-        });
+        if (topicId) {
+            // Forum topics require raw API call with InputReplyToMessage
+            const peer = await this.client.getInputEntity(chatId);
+            await this.client.invoke(new Api.messages.SendMessage({
+                peer,
+                message: text,
+                randomId: bigInt(Math.floor(Math.random() * 1e15)),
+                replyTo: new Api.InputReplyToMessage({
+                    replyToMsgId: replyTo ?? topicId,
+                    topMsgId: topicId,
+                }),
+            }));
+        }
+        else {
+            await this.client.sendMessage(chatId, {
+                message: text,
+                ...(replyTo ? { replyTo } : {}),
+                ...(parseMode ? { parseMode: parseMode === "html" ? "html" : "md" } : {}),
+            });
+        }
     }
     async sendFile(chatId, filePath, caption) {
         if (!this.client || !this.connected)
@@ -374,12 +389,11 @@ export class TelegramService {
         if (!this.client || !this.connected)
             throw new Error("Not connected");
         const dialogs = await this.client.getDialogs({ limit: limit * 3 });
-        return dialogs
-            .filter((d) => d.unreadCount > 0)
-            .slice(0, limit)
-            .map((d) => {
+        const unread = dialogs.filter((d) => d.unreadCount > 0).slice(0, limit);
+        const results = await Promise.all(unread.map(async (d) => {
             const isUser = d.entity instanceof Api.User;
-            return {
+            const isForum = d.entity instanceof Api.Channel && Boolean(d.entity.forum);
+            const base = {
                 id: d.id?.toString() ?? "",
                 name: d.title ?? d.name ?? "Unknown",
                 type: d.isGroup ? "group" : d.isChannel ? "channel" : "private",
@@ -388,7 +402,29 @@ export class TelegramService {
                     ? { isBot: Boolean(d.entity.bot), isContact: Boolean(d.entity.contact) }
                     : {}),
             };
-        });
+            if (isForum) {
+                try {
+                    const forumTopics = await this.getForumTopics(d.id?.toString() ?? "");
+                    const unreadTopics = forumTopics
+                        .filter((t) => t.unreadCount > 0)
+                        .map((t) => ({ id: t.id, title: t.title, unreadCount: t.unreadCount }));
+                    const realUnread = unreadTopics.reduce((sum, t) => sum + t.unreadCount, 0);
+                    if (realUnread === 0)
+                        return null;
+                    return {
+                        ...base,
+                        unreadCount: realUnread,
+                        forum: true,
+                        topics: unreadTopics.length > 0 ? unreadTopics : undefined,
+                    };
+                }
+                catch {
+                    return { ...base, forum: true };
+                }
+            }
+            return base;
+        }));
+        return results.filter((r) => r !== null);
     }
     async getContactRequests(limit = 20) {
         if (!this.client || !this.connected)
@@ -493,6 +529,7 @@ export class TelegramService {
                 username: entity.username ?? undefined,
                 description,
                 membersCount,
+                forum: Boolean(entity.forum) || undefined,
             };
         }
         if (entity instanceof Api.Chat) {
@@ -769,6 +806,75 @@ export class TelegramService {
         }
         return 0;
     }
+    async getForumTopics(chatId, limit = 100) {
+        if (!this.client || !this.connected)
+            throw new Error("Not connected");
+        const entity = await this.client.getEntity(chatId);
+        if (!(entity instanceof Api.Channel))
+            throw new Error("Forum topics are only available in supergroups");
+        const result = await this.client.invoke(new Api.channels.GetForumTopics({
+            channel: entity,
+            limit,
+            offsetTopic: 0,
+            offsetDate: 0,
+            offsetId: 0,
+        }));
+        const topics = [];
+        for (const topic of result.topics) {
+            if (topic instanceof Api.ForumTopic) {
+                topics.push({
+                    id: topic.id,
+                    title: topic.title,
+                    unreadCount: topic.unreadCount,
+                    unreadMentions: topic.unreadMentionsCount,
+                    iconColor: topic.iconColor,
+                    closed: Boolean(topic.closed),
+                    pinned: Boolean(topic.pinned),
+                });
+            }
+        }
+        return topics;
+    }
+    async getTopicMessages(chatId, topicId, limit = 20, offsetId) {
+        if (!this.client || !this.connected)
+            throw new Error("Not connected");
+        const peer = await this.client.getInputEntity(chatId);
+        const result = await this.client.invoke(new Api.messages.GetReplies({
+            peer,
+            msgId: topicId,
+            limit,
+            ...(offsetId ? { offsetId } : {}),
+            offsetDate: 0,
+            addOffset: 0,
+            maxId: 0,
+            minId: 0,
+            hash: bigInt(0),
+        }));
+        const messages = "messages" in result ? result.messages : [];
+        const results = await Promise.all(messages
+            .filter((m) => m instanceof Api.Message)
+            .map(async (m) => ({
+            id: m.id,
+            text: m.message ?? "",
+            sender: await this.resolveSenderName(m.senderId),
+            date: new Date((m.date ?? 0) * 1000).toISOString(),
+            media: this.extractMediaInfo(m.media),
+        })));
+        return results;
+    }
+    /** Check if a chat entity is a forum (has topics enabled) */
+    async isForum(chatId) {
+        if (!this.client || !this.connected)
+            throw new Error("Not connected");
+        try {
+            const entity = await this.client.getEntity(chatId);
+            if (entity instanceof Api.Channel) {
+                return Boolean(entity.forum);
+            }
+        }
+        catch { }
+        return false;
+    }
     async joinChat(target) {
         if (!this.client)
             throw new Error("Not connected");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@overpod/mcp-telegram",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "MCP server for Telegram userbot — messages, media, reactions, polls & more. Built on GramJS/MTProto.",
   "type": "module",
   "main": "dist/index.js",