@overpod/mcp-telegram 1.14.0 → 1.15.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,16 @@ 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;
+    }>;
 }

package/dist/telegram-client.js

@@ -1187,4 +1187,78 @@ 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" };
+    }
 }

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: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@overpod/mcp-telegram",
-  "version": "1.14.0",
+  "version": "1.15.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",