@overpod/mcp-telegram 1.13.0 → 1.15.0

package/README.md

@@ -90,6 +90,32 @@ claude mcp add telegram-personal -s user \
 
 Each account gets its own session file — no conflicts.
 
+### Proxy Support
+
+If Telegram is blocked or you're running in a containerized environment (Docker, K3s), use a SOCKS5 or MTProxy:
+
+```bash
+# SOCKS5 proxy
+TELEGRAM_PROXY_IP=127.0.0.1 \
+TELEGRAM_PROXY_PORT=10808 \
+npx @overpod/mcp-telegram
+
+# MTProxy
+TELEGRAM_PROXY_IP=proxy.example.com \
+TELEGRAM_PROXY_PORT=443 \
+TELEGRAM_PROXY_SECRET=ee00000000000000000000000000000000 \
+npx @overpod/mcp-telegram
+```
+
+| Variable | Description |
+|----------|-------------|
+| `TELEGRAM_PROXY_IP` | Proxy server address |
+| `TELEGRAM_PROXY_PORT` | Proxy server port |
+| `TELEGRAM_PROXY_SOCKS_TYPE` | `4` or `5` (default: `5`) |
+| `TELEGRAM_PROXY_SECRET` | MTProxy secret (enables MTProxy mode) |
+| `TELEGRAM_PROXY_USERNAME` | Optional proxy auth |
+| `TELEGRAM_PROXY_PASSWORD` | Optional proxy auth |
+
 ## Installation Options
 
 ### npx (recommended, zero install)
@@ -506,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

@@ -17,6 +17,24 @@ const MIN_SESSION_LENGTH = 100;
 function resolveSessionPath(sessionPath) {
     return sessionPath ?? process.env.TELEGRAM_SESSION_PATH ?? DEFAULT_SESSION_FILE;
 }
+function resolveProxy() {
+    const ip = process.env.TELEGRAM_PROXY_IP;
+    const port = process.env.TELEGRAM_PROXY_PORT;
+    if (!ip || !port)
+        return undefined;
+    const secret = process.env.TELEGRAM_PROXY_SECRET;
+    if (secret) {
+        return { ip, port: Number(port), secret, MTProxy: true };
+    }
+    const socksType = Number(process.env.TELEGRAM_PROXY_SOCKS_TYPE || "5");
+    return {
+        ip,
+        port: Number(port),
+        socksType: socksType,
+        ...(process.env.TELEGRAM_PROXY_USERNAME && { username: process.env.TELEGRAM_PROXY_USERNAME }),
+        ...(process.env.TELEGRAM_PROXY_PASSWORD && { password: process.env.TELEGRAM_PROXY_PASSWORD }),
+    };
+}
 function ensureSessionDir(filePath) {
     const dir = dirname(filePath);
     if (!existsSync(dir)) {
@@ -96,8 +114,10 @@ export class TelegramService {
                 return false;
         }
         const session = new StringSession(this.sessionString);
+        const proxy = resolveProxy();
         this.client = new TelegramClient(session, this.apiId, this.apiHash, {
             connectionRetries: 5,
+            ...(proxy && { proxy }),
         });
         try {
             await this.client.connect();
@@ -183,8 +203,10 @@ export class TelegramService {
     }
     async startQrLogin(onQrDataUrl, onQrUrl) {
         const session = new StringSession("");
+        const proxy = resolveProxy();
         const client = new TelegramClient(session, this.apiId, this.apiHash, {
             connectionRetries: 5,
+            ...(proxy && { proxy }),
         });
         try {
             await client.connect();
@@ -1165,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.13.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",