@overpod/mcp-telegram 1.14.0 → 1.16.0

package/README.md

@@ -532,12 +532,31 @@ src/
 - **[tsx](https://tsx.is/)** -- TypeScript execution without a build step
 - **[dotenv](https://github.com/motdotla/dotenv)** -- Environment variable management
 
+## Troubleshooting
+
+### AUTH_KEY_DUPLICATED
+
+A Telegram session can only be used by **one process at a time**. If you get `AUTH_KEY_DUPLICATED`, it means another process is already using the same session file.
+
+**Solution**: Create separate sessions for each environment:
+
+```bash
+# Local development
+TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-local npx @overpod/mcp-telegram login
+
+# Production server
+TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-prod npx @overpod/mcp-telegram login
+```
+
+Then set `TELEGRAM_SESSION_PATH` in each environment's MCP config accordingly.
+
 ## Security
 
 - API credentials are stored in `.env` (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
+- **One session per process** -- using the same session in multiple processes simultaneously causes `AUTH_KEY_DUPLICATED` errors (see [Troubleshooting](#troubleshooting))
 - This is a **userbot** (personal account), not a bot -- respect the [Telegram Terms of Service](https://core.telegram.org/api/terms)
 
 ## License

package/dist/telegram-client.d.ts

@@ -255,4 +255,33 @@ export declare class TelegramService {
         title: string;
         type: string;
     }>;
+    createGroup(options: {
+        title: string;
+        users: string[];
+        supergroup?: boolean;
+        forum?: boolean;
+        description?: string;
+    }): Promise<{
+        id: string;
+        title: string;
+        type: string;
+        inviteLink?: string;
+    }>;
+    inviteToGroup(chatId: string, users: string[]): Promise<{
+        invited: string[];
+        failed: string[];
+    }>;
+    kickUser(chatId: string, userId: string): Promise<void>;
+    banUser(chatId: string, userId: string): Promise<void>;
+    unbanUser(chatId: string, userId: string): Promise<void>;
+    editGroup(chatId: string, options: {
+        title?: string;
+        description?: string;
+        photoPath?: string;
+    }): Promise<void>;
+    leaveGroup(chatId: string): Promise<void>;
+    setAdmin(chatId: string, userId: string, options?: {
+        title?: string;
+    }): Promise<void>;
+    removeAdmin(chatId: string, userId: string): Promise<void>;
 }

package/dist/telegram-client.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { chmod, readFile, unlink, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
@@ -6,6 +6,7 @@ import { fileURLToPath } from "node:url";
 import bigInt from "big-integer";
 import QRCode from "qrcode";
 import { TelegramClient } from "telegram";
+import { CustomFile } from "telegram/client/uploads.js";
 import { StringSession } from "telegram/sessions/index.js";
 import { Api } from "telegram/tl/index.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -1187,4 +1188,253 @@ export class TelegramService {
         }
         throw new Error("Target is not a group or channel. Use username, @username, or invite link.");
     }
+    async createGroup(options) {
+        if (!this.client)
+            throw new Error("Not connected");
+        const { title, users, supergroup = false, forum = false, description } = options;
+        if (supergroup || forum) {
+            // Create supergroup/channel via channels.CreateChannel
+            const result = await this.client.invoke(new Api.channels.CreateChannel({
+                title,
+                about: description ?? "",
+                megagroup: true,
+                forum: forum || undefined,
+            }));
+            const chat = result.chats?.[0];
+            if (!chat)
+                throw new Error("Failed to create supergroup");
+            const channelId = chat.id.toString();
+            // Invite users
+            if (users.length > 0) {
+                const inputUsers = [];
+                for (const u of users) {
+                    try {
+                        const entity = await this.client.getEntity(u);
+                        if (entity instanceof Api.User) {
+                            inputUsers.push(new Api.InputUser({ userId: entity.id, accessHash: entity.accessHash ?? bigInt.zero }));
+                        }
+                    }
+                    catch {
+                        // Skip unresolvable users
+                    }
+                }
+                if (inputUsers.length > 0) {
+                    await this.client.invoke(new Api.channels.InviteToChannel({
+                        channel: chat,
+                        users: inputUsers,
+                    }));
+                }
+            }
+            // Get invite link
+            let inviteLink;
+            try {
+                const exported = await this.client.invoke(new Api.messages.ExportChatInvite({ peer: chat }));
+                if (exported instanceof Api.ChatInviteExported) {
+                    inviteLink = exported.link;
+                }
+            }
+            catch { }
+            return { id: channelId, title, type: forum ? "forum" : "supergroup", inviteLink };
+        }
+        // Create basic group via messages.CreateChat
+        const inputUsers = [];
+        for (const u of users) {
+            try {
+                const entity = await this.client.getEntity(u);
+                if (entity instanceof Api.User) {
+                    inputUsers.push(new Api.InputUser({ userId: entity.id, accessHash: entity.accessHash ?? bigInt.zero }));
+                }
+            }
+            catch {
+                // Skip unresolvable users
+            }
+        }
+        if (inputUsers.length === 0) {
+            throw new Error("At least one valid user is required to create a basic group");
+        }
+        const result = await this.client.invoke(new Api.messages.CreateChat({
+            title,
+            users: inputUsers,
+        }));
+        const updates = result;
+        const chat = updates.chats?.[0];
+        if (!chat)
+            throw new Error("Failed to create group");
+        return { id: chat.id.toString(), title, type: "group" };
+    }
+    async inviteToGroup(chatId, users) {
+        if (!this.client)
+            throw new Error("Not connected");
+        const entity = await this.client.getEntity(chatId);
+        const invited = [];
+        const failed = [];
+        for (const u of users) {
+            try {
+                const user = await this.client.getEntity(u);
+                if (!(user instanceof Api.User)) {
+                    failed.push(u);
+                    continue;
+                }
+                const inputUser = new Api.InputUser({ userId: user.id, accessHash: user.accessHash ?? bigInt.zero });
+                if (entity instanceof Api.Channel) {
+                    await this.client.invoke(new Api.channels.InviteToChannel({ channel: entity, users: [inputUser] }));
+                }
+                else if (entity instanceof Api.Chat) {
+                    await this.client.invoke(new Api.messages.AddChatUser({ chatId: entity.id, userId: inputUser, fwdLimit: 50 }));
+                }
+                invited.push(u);
+            }
+            catch {
+                failed.push(u);
+            }
+        }
+        return { invited, failed };
+    }
+    async kickUser(chatId, userId) {
+        if (!this.client)
+            throw new Error("Not connected");
+        const entity = await this.client.getEntity(chatId);
+        const user = await this.client.getEntity(userId);
+        if (!(user instanceof Api.User))
+            throw new Error("Target is not a user");
+        const inputUser = new Api.InputUser({ userId: user.id, accessHash: user.accessHash ?? bigInt.zero });
+        if (entity instanceof Api.Channel) {
+            // Kick = ban + unban (removes without permanent ban)
+            await this.client.invoke(new Api.channels.EditBanned({
+                channel: entity,
+                participant: inputUser,
+                bannedRights: new Api.ChatBannedRights({ untilDate: 0, viewMessages: true }),
+            }));
+            await this.client.invoke(new Api.channels.EditBanned({
+                channel: entity,
+                participant: inputUser,
+                bannedRights: new Api.ChatBannedRights({ untilDate: 0 }),
+            }));
+        }
+        else if (entity instanceof Api.Chat) {
+            await this.client.invoke(new Api.messages.DeleteChatUser({ chatId: entity.id, userId: inputUser }));
+        }
+    }
+    async banUser(chatId, userId) {
+        if (!this.client)
+            throw new Error("Not connected");
+        const entity = await this.client.getEntity(chatId);
+        const user = await this.client.getEntity(userId);
+        if (!(user instanceof Api.User))
+            throw new Error("Target is not a user");
+        if (!(entity instanceof Api.Channel))
+            throw new Error("Ban is only supported for supergroups and channels");
+        const inputUser = new Api.InputUser({ userId: user.id, accessHash: user.accessHash ?? bigInt.zero });
+        await this.client.invoke(new Api.channels.EditBanned({
+            channel: entity,
+            participant: inputUser,
+            bannedRights: new Api.ChatBannedRights({ untilDate: 0, viewMessages: true }),
+        }));
+    }
+    async unbanUser(chatId, userId) {
+        if (!this.client)
+            throw new Error("Not connected");
+        const entity = await this.client.getEntity(chatId);
+        const user = await this.client.getEntity(userId);
+        if (!(user instanceof Api.User))
+            throw new Error("Target is not a user");
+        if (!(entity instanceof Api.Channel))
+            throw new Error("Unban is only supported for supergroups and channels");
+        const inputUser = new Api.InputUser({ userId: user.id, accessHash: user.accessHash ?? bigInt.zero });
+        await this.client.invoke(new Api.channels.EditBanned({
+            channel: entity,
+            participant: inputUser,
+            bannedRights: new Api.ChatBannedRights({ untilDate: 0 }),
+        }));
+    }
+    async editGroup(chatId, options) {
+        if (!this.client)
+            throw new Error("Not connected");
+        const entity = await this.client.getEntity(chatId);
+        if (options.title) {
+            if (entity instanceof Api.Channel) {
+                await this.client.invoke(new Api.channels.EditTitle({ channel: entity, title: options.title }));
+            }
+            else if (entity instanceof Api.Chat) {
+                await this.client.invoke(new Api.messages.EditChatTitle({ chatId: entity.id, title: options.title }));
+            }
+        }
+        if (options.description != null) {
+            await this.client.invoke(new Api.messages.EditChatAbout({ peer: entity, about: options.description }));
+        }
+        if (options.photoPath) {
+            const fileData = readFileSync(options.photoPath);
+            const uploaded = await this.client.uploadFile({
+                file: new CustomFile(options.photoPath, fileData.length, options.photoPath, fileData),
+                workers: 1,
+            });
+            const inputPhoto = new Api.InputChatUploadedPhoto({ file: uploaded });
+            if (entity instanceof Api.Channel) {
+                await this.client.invoke(new Api.channels.EditPhoto({ channel: entity, photo: inputPhoto }));
+            }
+            else if (entity instanceof Api.Chat) {
+                await this.client.invoke(new Api.messages.EditChatPhoto({ chatId: entity.id, photo: inputPhoto }));
+            }
+        }
+    }
+    async leaveGroup(chatId) {
+        if (!this.client)
+            throw new Error("Not connected");
+        const entity = await this.client.getEntity(chatId);
+        if (entity instanceof Api.Channel) {
+            await this.client.invoke(new Api.channels.LeaveChannel({ channel: entity }));
+        }
+        else if (entity instanceof Api.Chat) {
+            await this.client.invoke(new Api.messages.DeleteChatUser({
+                chatId: entity.id,
+                userId: new Api.InputUserSelf(),
+            }));
+        }
+        else {
+            throw new Error("Target is not a group or channel");
+        }
+    }
+    async setAdmin(chatId, userId, options) {
+        if (!this.client)
+            throw new Error("Not connected");
+        const entity = await this.client.getEntity(chatId);
+        if (!(entity instanceof Api.Channel))
+            throw new Error("Set admin is only supported for supergroups and channels");
+        const user = await this.client.getEntity(userId);
+        if (!(user instanceof Api.User))
+            throw new Error("Target is not a user");
+        const inputUser = new Api.InputUser({ userId: user.id, accessHash: user.accessHash ?? bigInt.zero });
+        await this.client.invoke(new Api.channels.EditAdmin({
+            channel: entity,
+            userId: inputUser,
+            adminRights: new Api.ChatAdminRights({
+                changeInfo: true,
+                postMessages: true,
+                editMessages: true,
+                deleteMessages: true,
+                banUsers: true,
+                inviteUsers: true,
+                pinMessages: true,
+                manageCall: true,
+            }),
+            rank: options?.title ?? "",
+        }));
+    }
+    async removeAdmin(chatId, userId) {
+        if (!this.client)
+            throw new Error("Not connected");
+        const entity = await this.client.getEntity(chatId);
+        if (!(entity instanceof Api.Channel))
+            throw new Error("Remove admin is only supported for supergroups and channels");
+        const user = await this.client.getEntity(userId);
+        if (!(user instanceof Api.User))
+            throw new Error("Target is not a user");
+        const inputUser = new Api.InputUser({ userId: user.id, accessHash: user.accessHash ?? bigInt.zero });
+        await this.client.invoke(new Api.channels.EditAdmin({
+            channel: entity,
+            userId: inputUser,
+            adminRights: new Api.ChatAdminRights({}),
+            rank: "",
+        }));
+    }
 }

package/dist/tools/chats.js

@@ -100,6 +100,33 @@ export function registerChatTools(server, telegram) {
             return fail(e);
         }
     });
+    server.registerTool("telegram-create-group", {
+        description: "Create a new Telegram group or supergroup",
+        inputSchema: {
+            title: z.string().describe("Group name"),
+            users: z.array(z.string()).describe("Usernames or IDs to invite"),
+            supergroup: z.boolean().default(false).describe("Create as supergroup (supports >200 members, admin features)"),
+            forum: z.boolean().default(false).describe("Enable topics (requires supergroup)"),
+            description: z.string().optional().describe("Group description"),
+        },
+        annotations: WRITE,
+    }, async ({ title, users, supergroup, forum, description }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.createGroup({ title, users, supergroup, forum, description });
+            const lines = [
+                `Created ${result.type}: ${result.title}`,
+                `ID: ${result.id}`,
+                ...(result.inviteLink ? [`Invite link: ${result.inviteLink}`] : []),
+            ];
+            return ok(lines.join("\n"));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
     server.registerTool("telegram-join-chat", {
         description: "Join a Telegram group or channel by username or invite link",
         inputSchema: {
@@ -118,4 +145,164 @@ export function registerChatTools(server, telegram) {
             return fail(e);
         }
     });
+    server.registerTool("telegram-leave-group", {
+        description: "Leave a Telegram group or channel",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.leaveGroup(chatId);
+            return ok(`Left chat ${chatId}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-invite-to-group", {
+        description: "Invite users to a Telegram group or channel",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            users: z.array(z.string()).describe("Usernames or IDs to invite"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, users }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.inviteToGroup(chatId, users);
+            const lines = [];
+            if (result.invited.length > 0)
+                lines.push(`Invited: ${result.invited.join(", ")}`);
+            if (result.failed.length > 0)
+                lines.push(`Failed: ${result.failed.join(", ")}`);
+            return ok(lines.join("\n") || "No users processed");
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-kick-user", {
+        description: "Kick a user from a Telegram group (removes without permanent ban)",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            userId: z.string().describe("User ID or username to kick"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, userId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.kickUser(chatId, userId);
+            return ok(`Kicked ${userId} from ${chatId}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-ban-user", {
+        description: "Ban a user from a supergroup or channel (permanent until unbanned)",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            userId: z.string().describe("User ID or username to ban"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, userId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.banUser(chatId, userId);
+            return ok(`Banned ${userId} from ${chatId}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-unban-user", {
+        description: "Unban a previously banned user from a supergroup or channel",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            userId: z.string().describe("User ID or username to unban"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, userId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.unbanUser(chatId, userId);
+            return ok(`Unbanned ${userId} in ${chatId}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-edit-group", {
+        description: "Edit a group's title, description, or photo",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            title: z.string().optional().describe("New group title"),
+            description: z.string().optional().describe("New group description (supergroups only)"),
+            photoPath: z.string().optional().describe("Absolute path to new group photo image file"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, title, description, photoPath }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.editGroup(chatId, { title, description, photoPath });
+            const changed = [title && "title", description != null && "description", photoPath && "photo"].filter(Boolean);
+            return ok(`Updated ${changed.join(", ")} for ${chatId}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-set-admin", {
+        description: "Promote a user to admin in a supergroup or channel with full permissions",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            userId: z.string().describe("User ID or username to promote"),
+            title: z.string().optional().describe("Custom admin title"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, userId, title }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.setAdmin(chatId, userId, { title });
+            return ok(`Promoted ${userId} to admin in ${chatId}${title ? ` (${title})` : ""}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-remove-admin", {
+        description: "Remove admin rights from a user in a supergroup or channel",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            userId: z.string().describe("User ID or username to demote"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, userId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.removeAdmin(chatId, userId);
+            return ok(`Removed admin rights from ${userId} in ${chatId}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@overpod/mcp-telegram",
-  "version": "1.14.0",
+  "version": "1.16.0",
   "description": "MCP server for Telegram userbot — messages, media, reactions, polls & more. Built on GramJS/MTProto.",
   "type": "module",
   "main": "dist/index.js",
@@ -56,7 +56,7 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.8",
+    "@biomejs/biome": "^2.4.9",
     "@types/node": "^25.5.0",
     "@types/qrcode": "^1.5.6",
     "tsx": "^4.21.0",