@overpod/mcp-telegram 1.13.0 → 1.14.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)

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();

package/package.json

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