@mcp_factory/telegram-mcp-server 1.0.0

package/README.md

@@ -0,0 +1,81 @@
+# @mcp_factory/telegram-mcp-server
+
+MCP server for Telegram with built-in MTProto authentication.
+
+Read chats, send messages, search across conversations, manage contacts, forward, pin, and delete messages - all through MCP.
+
+## Setup (one time)
+
+### 1. Get Telegram API credentials
+Go to https://my.telegram.org/apps and create an app. Copy the `api_id` and `api_hash`.
+
+### 2. Run auth
+```bash
+TG_API_ID=12345 TG_API_HASH=abc123 npx @mcp_factory/telegram-mcp-server auth
+```
+
+A browser window opens where you:
+1. Enter your phone number
+2. Enter the OTP code from Telegram
+3. (If 2FA enabled) Enter your password
+
+Session is saved to `~/.telegram-mcp/session.json`. You only do this once.
+
+## Usage
+
+```bash
+TG_API_ID=12345 TG_API_HASH=abc123 npx @mcp_factory/telegram-mcp-server
+```
+
+Or in Claude Desktop `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "telegram": {
+      "command": "npx",
+      "args": ["-y", "@mcp_factory/telegram-mcp-server"],
+      "env": {
+        "TG_API_ID": "12345",
+        "TG_API_HASH": "abc123"
+      }
+    }
+  }
+}
+```
+
+On first run with no session, the browser opens automatically for login.
+
+## Available Tools (11)
+
+| Tool | Description |
+|------|-------------|
+| `telegram_get_me` | Get connected user's profile |
+| `telegram_list_chats` | List recent chats with unread counts |
+| `telegram_get_messages` | Get messages from a chat |
+| `telegram_send_message` | Send a message to any chat |
+| `telegram_search_messages` | Search messages (in chat or globally) |
+| `telegram_get_contacts` | Get contact list |
+| `telegram_get_chat_info` | Get chat/group/channel details |
+| `telegram_mark_read` | Mark chat as read |
+| `telegram_forward_message` | Forward messages between chats |
+| `telegram_delete_messages` | Delete messages |
+| `telegram_pin_message` | Pin a message in chat |
+
+## Auth Types
+
+| Context | How it works |
+|---------|-------------|
+| **Standalone** | Built-in web UI: phone + OTP + optional 2FA |
+| **MCP Bind / Wexa** | Backend handles MTProto session via `/telegram/sendCode` and `/telegram/verifyCode` APIs |
+
+## Security
+
+- Session stored locally at `~/.telegram-mcp/session.json` (file permissions: 600)
+- No data sent to third-party servers
+- Session = full account access - treat it like a password
+- Only runs on `127.0.0.1` during auth (not exposed to network)
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import("../dist/index.js");

package/dist/auth-server.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Auth Server
+ *
+ * Spins up a local HTTP server with a web UI for Telegram OTP verification.
+ * Flow: Phone number → Send OTP → Verify code → (optional 2FA) → Session saved
+ */
+export declare function startAuthServer(port?: number): Promise<{
+    port: number;
+    close: () => void;
+}>;
+/**
+ * Run auth flow: start server, open browser, wait for completion
+ */
+export declare function runAuthFlow(): Promise<void>;

package/dist/auth-server.js

@@ -0,0 +1,214 @@
+/**
+ * Auth Server
+ *
+ * Spins up a local HTTP server with a web UI for Telegram OTP verification.
+ * Flow: Phone number → Send OTP → Verify code → (optional 2FA) → Session saved
+ */
+import { createServer } from "http";
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { exec } from "child_process";
+import { TelegramClient } from "telegram";
+import { StringSession } from "telegram/sessions/index.js";
+import { saveSession } from "./session-manager.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// GramJS client state during auth
+let client = null;
+let pendingPhoneCodeHash = null;
+function getApiCredentials() {
+    const apiId = parseInt(process.env.TG_API_ID || process.env.TELEGRAM_API_ID || "0", 10);
+    const apiHash = process.env.TG_API_HASH || process.env.TELEGRAM_API_HASH || "";
+    if (!apiId || !apiHash) {
+        throw new Error("Missing Telegram API credentials.\n" +
+            "Set TG_API_ID and TG_API_HASH env vars.\n" +
+            "Get them at: https://my.telegram.org/apps");
+    }
+    return { apiId, apiHash };
+}
+async function handleAPI(req, res, body) {
+    const url = new URL(req.url || "/", "http://localhost");
+    const path = url.pathname;
+    res.setHeader("Content-Type", "application/json");
+    try {
+        if (path === "/api/send-code" && req.method === "POST") {
+            const { phone } = JSON.parse(body);
+            if (!phone) {
+                res.writeHead(400);
+                res.end(JSON.stringify({ error: "Phone number required" }));
+                return;
+            }
+            const { apiId, apiHash } = getApiCredentials();
+            client = new TelegramClient(new StringSession(""), apiId, apiHash, {
+                connectionRetries: 5,
+            });
+            await client.connect();
+            const result = await client.sendCode({ apiId, apiHash }, phone);
+            pendingPhoneCodeHash = result.phoneCodeHash;
+            res.writeHead(200);
+            res.end(JSON.stringify({ success: true, phoneCodeHash: result.phoneCodeHash }));
+        }
+        else if (path === "/api/verify-code" && req.method === "POST") {
+            const { phone, code, phoneCodeHash } = JSON.parse(body);
+            if (!client || !phone || !code) {
+                res.writeHead(400);
+                res.end(JSON.stringify({ error: "Missing phone, code, or session expired. Restart the flow." }));
+                return;
+            }
+            try {
+                await client.invoke(new (await import("telegram/tl/index.js")).Api.auth.SignIn({
+                    phoneNumber: phone,
+                    phoneCodeHash: phoneCodeHash || pendingPhoneCodeHash || "",
+                    phoneCode: code,
+                }));
+                // Success — save session
+                const sessionStr = client.session.save();
+                const me = await client.getMe();
+                saveSession({
+                    stringSession: sessionStr,
+                    userId: me?.id?.toString(),
+                    username: me?.username || undefined,
+                    firstName: me?.firstName || undefined,
+                    connectedAt: new Date().toISOString(),
+                });
+                res.writeHead(200);
+                res.end(JSON.stringify({ success: true, username: me?.username }));
+            }
+            catch (err) {
+                // Check if 2FA is needed
+                if (err.message?.includes("SESSION_PASSWORD_NEEDED")) {
+                    res.writeHead(400);
+                    res.end(JSON.stringify({ error: "2FA password required", need2FA: true }));
+                    return;
+                }
+                throw err;
+            }
+        }
+        else if (path === "/api/verify-2fa" && req.method === "POST") {
+            const { password } = JSON.parse(body);
+            if (!client || !password) {
+                res.writeHead(400);
+                res.end(JSON.stringify({ error: "Missing password or session expired" }));
+                return;
+            }
+            // Use GramJS built-in 2FA sign-in
+            await client.signInWithPassword({ apiId: getApiCredentials().apiId, apiHash: getApiCredentials().apiHash }, { password: () => Promise.resolve(password), onError: (e) => { throw e; } });
+            const sessionStr = client.session.save();
+            const me = await client.getMe();
+            saveSession({
+                stringSession: sessionStr,
+                userId: me?.id?.toString(),
+                username: me?.username || undefined,
+                firstName: me?.firstName || undefined,
+                connectedAt: new Date().toISOString(),
+            });
+            res.writeHead(200);
+            res.end(JSON.stringify({ success: true, username: me?.username }));
+        }
+        else {
+            res.writeHead(404);
+            res.end(JSON.stringify({ error: "Not found" }));
+        }
+    }
+    catch (err) {
+        console.error("Auth API error:", err.message);
+        res.writeHead(500);
+        res.end(JSON.stringify({ error: err.message || "Internal error" }));
+    }
+}
+function serveHTML(_req, res) {
+    // Try to find auth.html - check multiple locations
+    const candidates = [
+        join(__dirname, "..", "public", "auth.html"),
+        join(__dirname, "..", "..", "public", "auth.html"),
+    ];
+    for (const path of candidates) {
+        try {
+            const html = readFileSync(path, "utf-8");
+            res.writeHead(200, { "Content-Type": "text/html" });
+            res.end(html);
+            return;
+        }
+        catch {
+            continue;
+        }
+    }
+    // Fallback: inline minimal HTML
+    res.writeHead(200, { "Content-Type": "text/html" });
+    res.end(`<html><body><h2>Auth page not found. Check installation.</h2></body></html>`);
+}
+export function startAuthServer(port = 0) {
+    return new Promise((resolve, reject) => {
+        const server = createServer((req, res) => {
+            const url = new URL(req.url || "/", "http://localhost");
+            if (url.pathname.startsWith("/api/")) {
+                let body = "";
+                req.on("data", (chunk) => (body += chunk));
+                req.on("end", () => handleAPI(req, res, body));
+            }
+            else {
+                serveHTML(req, res);
+            }
+        });
+        server.listen(port, "127.0.0.1", () => {
+            const addr = server.address();
+            const actualPort = addr.port;
+            resolve({
+                port: actualPort,
+                close: () => {
+                    server.close();
+                    if (client) {
+                        client.disconnect().catch(() => { });
+                        client = null;
+                    }
+                },
+            });
+        });
+        server.on("error", reject);
+    });
+}
+/**
+ * Run auth flow: start server, open browser, wait for completion
+ */
+export async function runAuthFlow() {
+    const { apiId, apiHash } = getApiCredentials();
+    console.error(`Telegram API ID: ${apiId}`);
+    const { port, close } = await startAuthServer(0);
+    const url = `http://localhost:${port}`;
+    console.error(`\nTelegram auth server running at: ${url}`);
+    console.error("Opening browser...\n");
+    openBrowser(url);
+    // Wait for session to be saved (poll every second, timeout 3 min)
+    const { hasSession } = await import("./session-manager.js");
+    const start = Date.now();
+    while (!hasSession() && Date.now() - start < 180_000) {
+        await new Promise((r) => setTimeout(r, 1000));
+    }
+    close();
+    if (hasSession()) {
+        console.error("Telegram connected successfully!");
+    }
+    else {
+        throw new Error("Auth flow timed out. Please try again.");
+    }
+}
+function openBrowser(url) {
+    const cmd = process.platform === "darwin"
+        ? `open "${url}"`
+        : process.platform === "win32"
+            ? `start "${url}"`
+            : `xdg-open "${url}"`;
+    exec(cmd, (err) => {
+        if (err) {
+            console.error(`Could not open browser. Visit: ${url}`);
+        }
+    });
+}
+// If run directly: start auth flow
+if (process.argv[1]?.includes("auth-server")) {
+    runAuthFlow().catch((e) => {
+        console.error("Auth failed:", e.message);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=auth-server.js.map

package/dist/auth-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-server.js","sourceRoot":"","sources":["../src/auth-server.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * Telegram MCP Server
+ *
+ * MCP server for Telegram via MTProto (GramJS).
+ * Supports: read chats, send messages, search, contacts, forward, pin, delete.
+ *
+ * Auth: Built-in OTP flow with local web UI.
+ *   - First run opens browser for phone + OTP verification
+ *   - Session cached at ~/.telegram-mcp/session.json
+ *   - Subsequent runs use cached session (no login needed)
+ *
+ * Usage:
+ *   TG_API_ID=xxx TG_API_HASH=yyy npx @mcp_factory/telegram-mcp-server
+ *
+ * Auth only:
+ *   TG_API_ID=xxx TG_API_HASH=yyy npx @mcp_factory/telegram-mcp-server auth
+ */
+declare function main(): Promise<void>;
+export { main };

package/dist/index.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+/**
+ * Telegram MCP Server
+ *
+ * MCP server for Telegram via MTProto (GramJS).
+ * Supports: read chats, send messages, search, contacts, forward, pin, delete.
+ *
+ * Auth: Built-in OTP flow with local web UI.
+ *   - First run opens browser for phone + OTP verification
+ *   - Session cached at ~/.telegram-mcp/session.json
+ *   - Subsequent runs use cached session (no login needed)
+ *
+ * Usage:
+ *   TG_API_ID=xxx TG_API_HASH=yyy npx @mcp_factory/telegram-mcp-server
+ *
+ * Auth only:
+ *   TG_API_ID=xxx TG_API_HASH=yyy npx @mcp_factory/telegram-mcp-server auth
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { getTools, handleToolCall } from "./tools.js";
+import { hasSession } from "./session-manager.js";
+import { runAuthFlow } from "./auth-server.js";
+const SERVER_NAME = "telegram-mcp-server";
+const SERVER_VERSION = "1.0.0";
+async function main() {
+    const args = process.argv.slice(2);
+    // `auth` subcommand: run auth flow only
+    if (args[0] === "auth") {
+        await runAuthFlow();
+        process.exit(0);
+    }
+    // Check for session, run auth if needed
+    if (!hasSession()) {
+        console.error("No Telegram session found. Starting auth flow...");
+        await runAuthFlow();
+    }
+    // Create MCP server
+    const server = new Server({ name: SERVER_NAME, version: SERVER_VERSION }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        return { tools: getTools() };
+    });
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: toolArgs } = request.params;
+        try {
+            const result = await handleToolCall(name, toolArgs || {});
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: typeof result === "string" ? result : JSON.stringify(result, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [{ type: "text", text: `Error: ${message}` }],
+                isError: true,
+            };
+        }
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`${SERVER_NAME} v${SERVER_VERSION} running on stdio`);
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});
+export { main };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/session-manager.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Session Manager
+ *
+ * Stores and retrieves Telegram MTProto sessions securely.
+ * Sessions are saved at ~/.telegram-mcp/session.json (chmod 600).
+ */
+export interface SessionData {
+    stringSession: string;
+    userId?: string;
+    username?: string;
+    firstName?: string;
+    connectedAt?: string;
+}
+export declare function loadSession(): SessionData | null;
+export declare function saveSession(data: SessionData): void;
+export declare function deleteSession(): void;
+export declare function hasSession(): boolean;
+export declare function getSessionDir(): string;

package/dist/session-manager.js

@@ -0,0 +1,44 @@
+/**
+ * Session Manager
+ *
+ * Stores and retrieves Telegram MTProto sessions securely.
+ * Sessions are saved at ~/.telegram-mcp/session.json (chmod 600).
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+const SESSION_DIR = join(homedir(), ".telegram-mcp");
+const SESSION_FILE = join(SESSION_DIR, "session.json");
+export function loadSession() {
+    try {
+        if (!existsSync(SESSION_FILE))
+            return null;
+        const raw = readFileSync(SESSION_FILE, "utf-8");
+        const data = JSON.parse(raw);
+        if (data.stringSession)
+            return data;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export function saveSession(data) {
+    if (!existsSync(SESSION_DIR)) {
+        mkdirSync(SESSION_DIR, { recursive: true });
+    }
+    writeFileSync(SESSION_FILE, JSON.stringify(data, null, 2), { mode: 0o600 });
+}
+export function deleteSession() {
+    if (existsSync(SESSION_FILE)) {
+        writeFileSync(SESSION_FILE, "{}", { mode: 0o600 });
+    }
+}
+export function hasSession() {
+    const session = loadSession();
+    return session !== null && session.stringSession.length > 0;
+}
+export function getSessionDir() {
+    return SESSION_DIR;
+}
+//# sourceMappingURL=session-manager.js.map

package/dist/session-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-manager.js","sourceRoot":"","sources":["../src/session-manager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AACxE,OAAO,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC;AAC7B,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE5B,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,eAAe,CAAC,CAAC;AACrD,MAAM,YAAY,GAAG,IAAI,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC;AAUvD,MAAM,UAAU,WAAW;IACzB,IAAI,CAAC;QACH,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC;YAAE,OAAO,IAAI,CAAC;QAC3C,MAAM,GAAG,GAAG,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;QAChD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,IAAI,CAAC,aAAa;YAAE,OAAO,IAAmB,CAAC;QACnD,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,IAAiB;IAC3C,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;QAC7B,SAAS,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,CAAC;IACD,aAAa,CAAC,YAAY,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;AAC9E,CAAC;AAED,MAAM,UAAU,aAAa;IAC3B,IAAI,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QAC7B,aAAa,CAAC,YAAY,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACrD,CAAC;AACH,CAAC;AAED,MAAM,UAAU,UAAU;IACxB,MAAM,OAAO,GAAG,WAAW,EAAE,CAAC;IAC9B,OAAO,OAAO,KAAK,IAAI,IAAI,OAAO,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,CAAC;AAC9D,CAAC;AAED,MAAM,UAAU,aAAa;IAC3B,OAAO,WAAW,CAAC;AACrB,CAAC"}

package/dist/telegram-client.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Telegram Client Wrapper
+ *
+ * Wraps GramJS TelegramClient for use by MCP tools.
+ * Handles session loading, connection, and provides high-level methods.
+ */
+import { TelegramClient } from "telegram";
+export declare function getClient(): Promise<TelegramClient>;
+export declare function getMe(): Promise<Record<string, unknown>>;
+export declare function getDialogs(limit?: number): Promise<unknown[]>;
+export declare function getMessages(chatId: string, limit?: number): Promise<unknown[]>;
+export declare function sendMessage(chatId: string, text: string): Promise<unknown>;
+export declare function searchMessages(chatId: string | undefined, query: string, limit?: number): Promise<unknown[]>;
+export declare function getContacts(): Promise<unknown[]>;
+export declare function getChatInfo(chatId: string): Promise<unknown>;
+export declare function markAsRead(chatId: string): Promise<void>;
+export declare function forwardMessage(fromChatId: string, toChatId: string, messageIds: number[]): Promise<unknown>;
+export declare function deleteMessages(chatId: string, messageIds: number[]): Promise<void>;
+export declare function pinMessage(chatId: string, messageId: number): Promise<void>;

package/dist/telegram-client.js

@@ -0,0 +1,163 @@
+/**
+ * Telegram Client Wrapper
+ *
+ * Wraps GramJS TelegramClient for use by MCP tools.
+ * Handles session loading, connection, and provides high-level methods.
+ */
+import { TelegramClient } from "telegram";
+import { StringSession } from "telegram/sessions/index.js";
+import { Api } from "telegram/tl/index.js";
+import { loadSession } from "./session-manager.js";
+let _client = null;
+export async function getClient() {
+    if (_client?.connected)
+        return _client;
+    const apiId = parseInt(process.env.TG_API_ID || process.env.TELEGRAM_API_ID || "0", 10);
+    const apiHash = process.env.TG_API_HASH || process.env.TELEGRAM_API_HASH || "";
+    if (!apiId || !apiHash) {
+        throw new Error("Set TG_API_ID and TG_API_HASH. Get them at https://my.telegram.org/apps");
+    }
+    const session = loadSession();
+    if (!session?.stringSession) {
+        throw new Error("No Telegram session found. Run the auth flow first:\n" +
+            "  npx @mcp_factory/telegram-mcp-server auth\n" +
+            "Or set TG_API_ID + TG_API_HASH and restart.");
+    }
+    _client = new TelegramClient(new StringSession(session.stringSession), apiId, apiHash, {
+        connectionRetries: 5,
+    });
+    await _client.connect();
+    return _client;
+}
+// --- High-level helpers ---
+export async function getMe() {
+    const client = await getClient();
+    const me = await client.getMe();
+    return {
+        id: me?.id?.toString(),
+        username: me?.username,
+        firstName: me?.firstName,
+        lastName: me?.lastName,
+        phone: me?.phone,
+    };
+}
+export async function getDialogs(limit = 20) {
+    const client = await getClient();
+    const dialogs = await client.getDialogs({ limit });
+    return dialogs.map((d) => ({
+        id: d.id?.toString(),
+        name: d.name || d.title,
+        unreadCount: d.unreadCount,
+        isUser: d.isUser,
+        isGroup: d.isGroup,
+        isChannel: d.isChannel,
+        lastMessage: d.message?.message?.substring(0, 100),
+        date: d.message?.date,
+    }));
+}
+export async function getMessages(chatId, limit = 20) {
+    const client = await getClient();
+    const entity = await client.getEntity(chatId);
+    const messages = await client.getMessages(entity, { limit });
+    return messages.map((m) => ({
+        id: m.id,
+        text: m.message,
+        date: m.date,
+        senderId: m.senderId?.toString(),
+        replyTo: m.replyTo?.replyToMsgId,
+        out: m.out,
+    }));
+}
+export async function sendMessage(chatId, text) {
+    const client = await getClient();
+    const entity = await client.getEntity(chatId);
+    const result = await client.sendMessage(entity, { message: text });
+    return {
+        id: result.id,
+        text: result.message,
+        date: result.date,
+        chatId: chatId,
+    };
+}
+export async function searchMessages(chatId, query, limit = 20) {
+    const client = await getClient();
+    if (chatId) {
+        const entity = await client.getEntity(chatId);
+        const messages = await client.getMessages(entity, { search: query, limit });
+        return messages.map((m) => ({
+            id: m.id,
+            text: m.message,
+            date: m.date,
+            chatId: chatId,
+            senderId: m.senderId?.toString(),
+        }));
+    }
+    // Global search
+    const result = await client.invoke(new Api.messages.SearchGlobal({
+        q: query,
+        filter: new Api.InputMessagesFilterEmpty(),
+        minDate: 0,
+        maxDate: 0,
+        offsetRate: 0,
+        offsetPeer: new Api.InputPeerEmpty(),
+        offsetId: 0,
+        limit,
+    }));
+    const messages = result.messages || [];
+    return messages.map((m) => ({
+        id: m.id,
+        text: m.message,
+        date: m.date,
+        peerId: m.peerId?.toString(),
+    }));
+}
+export async function getContacts() {
+    const client = await getClient();
+    const result = await client.invoke(new Api.contacts.GetContacts({ hash: 0 }));
+    const users = result.users || [];
+    return users.map((u) => ({
+        id: u.id?.toString(),
+        firstName: u.firstName,
+        lastName: u.lastName,
+        username: u.username,
+        phone: u.phone,
+    }));
+}
+export async function getChatInfo(chatId) {
+    const client = await getClient();
+    const entity = await client.getEntity(chatId);
+    return {
+        id: entity.id?.toString(),
+        title: entity.title || entity.firstName,
+        username: entity.username,
+        participantsCount: entity.participantsCount,
+        about: entity.about,
+        type: entity.className,
+    };
+}
+export async function markAsRead(chatId) {
+    const client = await getClient();
+    const entity = await client.getEntity(chatId);
+    await client.markAsRead(entity);
+}
+export async function forwardMessage(fromChatId, toChatId, messageIds) {
+    const client = await getClient();
+    const fromEntity = await client.getEntity(fromChatId);
+    const toEntity = await client.getEntity(toChatId);
+    const result = await client.forwardMessages(toEntity, {
+        messages: messageIds,
+        fromPeer: fromEntity,
+    });
+    return { forwarded: result.length };
+}
+export async function deleteMessages(chatId, messageIds) {
+    const client = await getClient();
+    const entity = await client.getEntity(chatId);
+    await client.deleteMessages(entity, messageIds, { revoke: true });
+}
+export async function pinMessage(chatId, messageId) {
+    const client = await getClient();
+    const entity = await client.getEntity(chatId);
+    await client.pinMessage(entity, messageId);
+}
+//# sourceMappingURL=telegram-client.js.map

package/dist/telegram-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telegram-client.js","sourceRoot":"","sources":["../src/telegram-client.ts"],"names":[],"mappings":"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"}

package/dist/tools.d.ts

@@ -0,0 +1,6 @@
+/**
+ * MCP Tool definitions and handlers for Telegram
+ */
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+export declare function getTools(): Tool[];
+export declare function handleToolCall(name: string, args: Record<string, unknown>): Promise<unknown>;

package/dist/tools.js

@@ -0,0 +1,163 @@
+import * as tg from "./telegram-client.js";
+const tools = [
+    {
+        name: "telegram_get_me",
+        description: "Get the connected Telegram user's profile info",
+        inputSchema: { type: "object", properties: {}, required: [] },
+    },
+    {
+        name: "telegram_list_chats",
+        description: "List recent Telegram chats/dialogs (DMs, groups, channels) with unread counts",
+        inputSchema: {
+            type: "object",
+            properties: {
+                limit: { type: "number", default: 20, description: "Max chats to return (default: 20)" },
+            },
+            required: [],
+        },
+    },
+    {
+        name: "telegram_get_messages",
+        description: "Get recent messages from a specific chat",
+        inputSchema: {
+            type: "object",
+            properties: {
+                chat_id: { type: "string", description: "Chat ID or @username" },
+                limit: { type: "number", default: 20, description: "Max messages (default: 20)" },
+            },
+            required: ["chat_id"],
+        },
+    },
+    {
+        name: "telegram_send_message",
+        description: "Send a text message to a Telegram chat, group, or user",
+        inputSchema: {
+            type: "object",
+            properties: {
+                chat_id: { type: "string", description: "Chat ID or @username" },
+                text: { type: "string", description: "Message text (supports Telegram markdown)" },
+            },
+            required: ["chat_id", "text"],
+        },
+    },
+    {
+        name: "telegram_search_messages",
+        description: "Search messages in a specific chat or globally across all chats",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "Search query" },
+                chat_id: { type: "string", description: "Chat ID to search in (omit for global search)" },
+                limit: { type: "number", default: 20, description: "Max results (default: 20)" },
+            },
+            required: ["query"],
+        },
+    },
+    {
+        name: "telegram_get_contacts",
+        description: "Get the user's Telegram contact list",
+        inputSchema: { type: "object", properties: {}, required: [] },
+    },
+    {
+        name: "telegram_get_chat_info",
+        description: "Get detailed info about a chat, group, or channel",
+        inputSchema: {
+            type: "object",
+            properties: {
+                chat_id: { type: "string", description: "Chat ID or @username" },
+            },
+            required: ["chat_id"],
+        },
+    },
+    {
+        name: "telegram_mark_read",
+        description: "Mark all messages in a chat as read",
+        inputSchema: {
+            type: "object",
+            properties: {
+                chat_id: { type: "string", description: "Chat ID or @username" },
+            },
+            required: ["chat_id"],
+        },
+    },
+    {
+        name: "telegram_forward_message",
+        description: "Forward messages from one chat to another",
+        inputSchema: {
+            type: "object",
+            properties: {
+                from_chat_id: { type: "string", description: "Source chat ID" },
+                to_chat_id: { type: "string", description: "Destination chat ID" },
+                message_ids: {
+                    type: "array",
+                    items: { type: "number" },
+                    description: "Array of message IDs to forward",
+                },
+            },
+            required: ["from_chat_id", "to_chat_id", "message_ids"],
+        },
+    },
+    {
+        name: "telegram_delete_messages",
+        description: "Delete messages from a chat (revokes for all participants)",
+        inputSchema: {
+            type: "object",
+            properties: {
+                chat_id: { type: "string", description: "Chat ID" },
+                message_ids: {
+                    type: "array",
+                    items: { type: "number" },
+                    description: "Array of message IDs to delete",
+                },
+            },
+            required: ["chat_id", "message_ids"],
+        },
+    },
+    {
+        name: "telegram_pin_message",
+        description: "Pin a message in a chat",
+        inputSchema: {
+            type: "object",
+            properties: {
+                chat_id: { type: "string", description: "Chat ID" },
+                message_id: { type: "number", description: "Message ID to pin" },
+            },
+            required: ["chat_id", "message_id"],
+        },
+    },
+];
+export function getTools() {
+    return tools;
+}
+export async function handleToolCall(name, args) {
+    switch (name) {
+        case "telegram_get_me":
+            return tg.getMe();
+        case "telegram_list_chats":
+            return tg.getDialogs(args.limit || 20);
+        case "telegram_get_messages":
+            return tg.getMessages(args.chat_id, args.limit || 20);
+        case "telegram_send_message":
+            return tg.sendMessage(args.chat_id, args.text);
+        case "telegram_search_messages":
+            return tg.searchMessages(args.chat_id, args.query, args.limit || 20);
+        case "telegram_get_contacts":
+            return tg.getContacts();
+        case "telegram_get_chat_info":
+            return tg.getChatInfo(args.chat_id);
+        case "telegram_mark_read":
+            await tg.markAsRead(args.chat_id);
+            return { success: true };
+        case "telegram_forward_message":
+            return tg.forwardMessage(args.from_chat_id, args.to_chat_id, args.message_ids);
+        case "telegram_delete_messages":
+            await tg.deleteMessages(args.chat_id, args.message_ids);
+            return { success: true };
+        case "telegram_pin_message":
+            await tg.pinMessage(args.chat_id, args.message_id);
+            return { success: true };
+        default:
+            throw new Error(`Unknown tool: ${name}. Available: ${tools.map((t) => t.name).join(", ")}`);
+    }
+}
+//# sourceMappingURL=tools.js.map

package/dist/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@mcp_factory/telegram-mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server for Telegram - read chats, send messages, manage contacts, search messages. Built-in MTProto auth with OTP verification UI.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "telegram-mcp-server": "./bin/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node bin/cli.js",
+    "auth": "node dist/auth-server.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "telegram",
+    "mtproto",
+    "gramjs"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "latest",
+    "telegram": "^2.26.0",
+    "input": "^1.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "public",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/public/auth.html

@@ -0,0 +1,277 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Telegram MCP - Connect Account</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      background: #0f0f0f;
+      color: #e4e4e4;
+      display: flex;
+      justify-content: center;
+      align-items: center;
+      min-height: 100vh;
+    }
+    .container {
+      background: #1a1a2e;
+      border-radius: 16px;
+      padding: 40px;
+      width: 400px;
+      box-shadow: 0 8px 32px rgba(0,0,0,0.4);
+    }
+    .logo {
+      text-align: center;
+      margin-bottom: 24px;
+    }
+    .logo svg { width: 48px; height: 48px; }
+    h1 {
+      text-align: center;
+      font-size: 22px;
+      margin-bottom: 8px;
+      color: #fff;
+    }
+    .subtitle {
+      text-align: center;
+      color: #888;
+      font-size: 14px;
+      margin-bottom: 32px;
+    }
+    .step { display: none; }
+    .step.active { display: block; }
+    label {
+      display: block;
+      font-size: 13px;
+      color: #aaa;
+      margin-bottom: 6px;
+    }
+    input {
+      width: 100%;
+      padding: 14px 16px;
+      border: 1px solid #333;
+      border-radius: 10px;
+      background: #0f0f1a;
+      color: #fff;
+      font-size: 16px;
+      outline: none;
+      margin-bottom: 16px;
+      transition: border 0.2s;
+    }
+    input:focus { border-color: #0088cc; }
+    input::placeholder { color: #555; }
+    button {
+      width: 100%;
+      padding: 14px;
+      border: none;
+      border-radius: 10px;
+      background: #0088cc;
+      color: #fff;
+      font-size: 16px;
+      font-weight: 600;
+      cursor: pointer;
+      transition: background 0.2s;
+    }
+    button:hover { background: #006daa; }
+    button:disabled { background: #333; cursor: not-allowed; }
+    .error {
+      background: #2d1515;
+      border: 1px solid #5c2020;
+      color: #ff6b6b;
+      padding: 12px;
+      border-radius: 8px;
+      font-size: 13px;
+      margin-bottom: 16px;
+      display: none;
+    }
+    .success {
+      text-align: center;
+      padding: 24px 0;
+    }
+    .success .check {
+      width: 64px;
+      height: 64px;
+      border-radius: 50%;
+      background: #0a3d1a;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      margin: 0 auto 16px;
+      font-size: 28px;
+    }
+    .info {
+      background: #1a1a3e;
+      border: 1px solid #2a2a5e;
+      padding: 12px;
+      border-radius: 8px;
+      font-size: 12px;
+      color: #888;
+      margin-top: 24px;
+      line-height: 1.5;
+    }
+    .spinner {
+      display: inline-block;
+      width: 16px;
+      height: 16px;
+      border: 2px solid #fff;
+      border-top-color: transparent;
+      border-radius: 50%;
+      animation: spin 0.6s linear infinite;
+      margin-right: 8px;
+      vertical-align: middle;
+    }
+    @keyframes spin { to { transform: rotate(360deg); } }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <div class="logo">
+      <svg viewBox="0 0 48 48" fill="none"><circle cx="24" cy="24" r="24" fill="#0088cc"/><path d="M10.6 23.4l24.2-9.4c1.1-.4 2.1.3 1.7 1.8l-4.1 19.3c-.3 1.3-1.1 1.6-2.2 1l-6.1-4.5-2.9 2.8c-.3.3-.6.6-1.3.6l.4-6.2 11-9.9c.5-.4-.1-.7-.7-.3L16 25l-6-1.9c-1.3-.4-1.3-1.3.3-1.9z" fill="#fff"/></svg>
+    </div>
+    <h1>Connect Telegram</h1>
+    <p class="subtitle">Link your Telegram account to MCP</p>
+
+    <div class="error" id="error"></div>
+
+    <!-- Step 1: Phone Number -->
+    <div class="step active" id="step-phone">
+      <label>Phone Number (with country code)</label>
+      <input type="tel" id="phone" placeholder="+1 234 567 8900" autofocus>
+      <button onclick="sendCode()" id="btn-send">Send Verification Code</button>
+    </div>
+
+    <!-- Step 2: OTP -->
+    <div class="step" id="step-otp">
+      <label>Verification Code</label>
+      <input type="text" id="otp" placeholder="Enter the code from Telegram" maxlength="6" inputmode="numeric">
+      <button onclick="verifyCode()" id="btn-verify">Verify & Connect</button>
+    </div>
+
+    <!-- Step 3: 2FA Password (if needed) -->
+    <div class="step" id="step-2fa">
+      <label>Two-Factor Password</label>
+      <input type="password" id="password" placeholder="Enter your 2FA password">
+      <button onclick="verify2FA()" id="btn-2fa">Submit Password</button>
+    </div>
+
+    <!-- Step 4: Success -->
+    <div class="step" id="step-success">
+      <div class="success">
+        <div class="check">&#10003;</div>
+        <h2 style="margin-bottom:8px">Connected!</h2>
+        <p style="color:#888">Your Telegram account is linked. You can close this tab.</p>
+      </div>
+    </div>
+
+    <div class="info">
+      Your session is stored locally at <code>~/.telegram-mcp/</code> and encrypted.
+      No data is sent to any third-party server.
+    </div>
+  </div>
+
+  <script>
+    let phoneHash = "";
+
+    function showError(msg) {
+      const el = document.getElementById("error");
+      el.textContent = msg;
+      el.style.display = msg ? "block" : "none";
+    }
+
+    function showStep(id) {
+      document.querySelectorAll(".step").forEach(s => s.classList.remove("active"));
+      document.getElementById("step-" + id).classList.add("active");
+      showError("");
+    }
+
+    function setLoading(btnId, loading) {
+      const btn = document.getElementById(btnId);
+      if (loading) {
+        btn.disabled = true;
+        btn.dataset.text = btn.textContent;
+        btn.innerHTML = '<span class="spinner"></span>Please wait...';
+      } else {
+        btn.disabled = false;
+        btn.textContent = btn.dataset.text;
+      }
+    }
+
+    async function sendCode() {
+      const phone = document.getElementById("phone").value.trim();
+      if (!phone || !phone.startsWith("+")) {
+        showError("Enter phone number with country code (e.g. +1234567890)");
+        return;
+      }
+      setLoading("btn-send", true);
+      try {
+        const res = await fetch("/api/send-code", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ phone }),
+        });
+        const data = await res.json();
+        if (!res.ok) throw new Error(data.error || "Failed to send code");
+        phoneHash = data.phoneCodeHash;
+        showStep("otp");
+        document.getElementById("otp").focus();
+      } catch (e) {
+        showError(e.message);
+      }
+      setLoading("btn-send", false);
+    }
+
+    async function verifyCode() {
+      const code = document.getElementById("otp").value.trim();
+      if (!code) { showError("Enter the verification code"); return; }
+      setLoading("btn-verify", true);
+      try {
+        const phone = document.getElementById("phone").value.trim();
+        const res = await fetch("/api/verify-code", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ phone, code, phoneCodeHash: phoneHash }),
+        });
+        const data = await res.json();
+        if (!res.ok) {
+          if (data.need2FA) {
+            showStep("2fa");
+            document.getElementById("password").focus();
+            setLoading("btn-verify", false);
+            return;
+          }
+          throw new Error(data.error || "Verification failed");
+        }
+        showStep("success");
+      } catch (e) {
+        showError(e.message);
+      }
+      setLoading("btn-verify", false);
+    }
+
+    async function verify2FA() {
+      const password = document.getElementById("password").value;
+      if (!password) { showError("Enter your 2FA password"); return; }
+      setLoading("btn-2fa", true);
+      try {
+        const res = await fetch("/api/verify-2fa", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ password }),
+        });
+        const data = await res.json();
+        if (!res.ok) throw new Error(data.error || "2FA verification failed");
+        showStep("success");
+      } catch (e) {
+        showError(e.message);
+      }
+      setLoading("btn-2fa", false);
+    }
+
+    // Enter key handlers
+    document.getElementById("phone").addEventListener("keydown", e => { if (e.key === "Enter") sendCode(); });
+    document.getElementById("otp").addEventListener("keydown", e => { if (e.key === "Enter") verifyCode(); });
+    document.getElementById("password").addEventListener("keydown", e => { if (e.key === "Enter") verify2FA(); });
+  </script>
+</body>
+</html>