@ebowwa/mcp-telegram 0.1.4

package/dist/index.js

@@ -0,0 +1,807 @@
+#!/usr/bin/env node
+/**
+ * @ebowwa/telegram-mcp - Telegram MTProto Client MCP Server
+ *
+ * Full-featured Telegram user account integration using GramJS:
+ * - Connect/authenticate with API ID and hash
+ * - Send messages to users, groups, channels
+ * - Get dialogs (chat list)
+ * - Get messages from chats
+ * - Get entity info (users, chats, channels)
+ *
+ * Prerequisites:
+ * 1. Get API ID and API Hash from https://my.telegram.org/apps
+ * 2. First connection requires phone number + verification code
+ * 3. Session string is saved for subsequent connections
+ */
+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 { TelegramClient } from "telegram";
+import { StringSession } from "telegram/sessions";
+import { Api } from "telegram";
+import bigInt from "big-integer";
+import { homedir } from "os";
+import { join } from "path";
+import { mkdirSync, existsSync, writeFileSync, readFileSync } from "fs";
+import { execSync } from "child_process";
+// ==============
+// Configuration
+// ==============
+const SESSION_DIR = join(homedir(), ".telegram-mcp");
+const SESSION_FILE = join(SESSION_DIR, "session.txt");
+// Ensure session directory exists
+if (!existsSync(SESSION_DIR)) {
+    mkdirSync(SESSION_DIR, { recursive: true });
+}
+// Global client instance
+let client = null;
+let sessionString = "";
+// ==============
+// Helper Functions
+// ==============
+async function loadSession() {
+    if (existsSync(SESSION_FILE)) {
+        return readFileSync(SESSION_FILE, "utf-8").trim();
+    }
+    return "";
+}
+async function saveSession(session) {
+    writeFileSync(SESSION_FILE, session, "utf-8");
+}
+async function getClient() {
+    if (client && client.connected) {
+        return client;
+    }
+    // Auto-connect using saved session
+    const apiId = parseInt(process.env.TELEGRAM_API_ID || "0");
+    const apiHash = process.env.TELEGRAM_API_HASH;
+    if (!apiId || !apiHash) {
+        throw new Error("TELEGRAM_API_ID and TELEGRAM_API_HASH environment variables required.");
+    }
+    const savedSession = await loadSession();
+    if (!savedSession) {
+        throw new Error("No saved session. Run telegram_connect with phone number first.");
+    }
+    const session = new StringSession(savedSession);
+    client = new TelegramClient(session, apiId, apiHash, {
+        connectionRetries: 5,
+    });
+    await client.connect();
+    if (!(await client.checkAuthorization())) {
+        client = null;
+        throw new Error("Session expired. Run telegram_connect again.");
+    }
+    return client;
+}
+function formatEntity(entity) {
+    if (!entity)
+        return null;
+    const base = {
+        id: entity.id?.toString(),
+        className: entity.className,
+    };
+    if (entity.className === "User") {
+        return {
+            ...base,
+            firstName: entity.firstName,
+            lastName: entity.lastName,
+            username: entity.username,
+            phone: entity.phone,
+            bot: entity.bot,
+        };
+    }
+    if (entity.className === "Chat" || entity.className === "Channel") {
+        return {
+            ...base,
+            title: entity.title,
+            username: entity.username,
+            megagroup: entity.megagroup,
+        };
+    }
+    return base;
+}
+function formatMessage(message) {
+    if (!message)
+        return null;
+    return {
+        id: message.id,
+        date: message.date ? new Date(message.date * 1000).toISOString() : null,
+        message: message.message,
+        fromId: message.fromId?.userId?.toString() || message.fromId?.toString(),
+        peerId: message.peerId?.userId?.toString() || message.peerId?.chatId?.toString() || message.peerId?.channelId?.toString(),
+        out: message.out,
+        media: message.media?.className,
+    };
+}
+// ==============
+// MCP Server
+// ==============
+const server = new Server({
+    name: "@ebowwa/telegram-mcp",
+    version: "0.1.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// List available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            // Connection Management
+            {
+                name: "telegram_connect",
+                description: "Connect to Telegram with API credentials. Requires TELEGRAM_API_ID and TELEGRAM_API_HASH env vars. First connection needs phone/code verification.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        phoneNumber: {
+                            type: "string",
+                            description: "Phone number with country code (e.g., +1234567890). Required for first connection.",
+                        },
+                        code: {
+                            type: "string",
+                            description: "Verification code received via Telegram. Required after initial phone submission.",
+                        },
+                        password: {
+                            type: "string",
+                            description: "2FA password if enabled on account.",
+                        },
+                        sessionString: {
+                            type: "string",
+                            description: "Existing session string to restore (optional, overrides saved session).",
+                        },
+                    },
+                },
+            },
+            {
+                name: "telegram_disconnect",
+                description: "Disconnect from Telegram and clear the session.",
+                inputSchema: {
+                    type: "object",
+                    properties: {},
+                },
+            },
+            {
+                name: "telegram_get_session",
+                description: "Get the current session string for backup/restore purposes.",
+                inputSchema: {
+                    type: "object",
+                    properties: {},
+                },
+            },
+            {
+                name: "telegram_get_me",
+                description: "Get information about the currently authenticated user.",
+                inputSchema: {
+                    type: "object",
+                    properties: {},
+                },
+            },
+            {
+                name: "telegram_restart",
+                description: "Restart the Telegram MCP systemd service. Useful for applying config changes or recovering from errors.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        serviceName: {
+                            type: "string",
+                            description: "Systemd service name (default: telegram-mcp)",
+                        },
+                    },
+                },
+            },
+            // Messaging
+            {
+                name: "telegram_send_message",
+                description: "Send a message to a user, group, or channel.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        entity: {
+                            type: "string",
+                            description: "Username, phone, or entity ID to send message to (e.g., 'username', '+1234567890', '123456789')",
+                        },
+                        message: {
+                            type: "string",
+                            description: "Message text to send",
+                        },
+                        parseMode: {
+                            type: "string",
+                            enum: ["md", "html", ""],
+                            description: "Parse mode for formatting (md=Markdown, html=HTML)",
+                        },
+                        replyTo: {
+                            type: "number",
+                            description: "Message ID to reply to (optional)",
+                        },
+                    },
+                    required: ["entity", "message"],
+                },
+            },
+            {
+                name: "telegram_get_dialogs",
+                description: "Get list of all chats/conversations (dialogs).",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        limit: {
+                            type: "number",
+                            description: "Maximum number of dialogs to return (default: 100)",
+                        },
+                        offsetDate: {
+                            type: "number",
+                            description: "Offset date for pagination",
+                        },
+                    },
+                },
+            },
+            {
+                name: "telegram_get_messages",
+                description: "Get messages from a chat/conversation.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        entity: {
+                            type: "string",
+                            description: "Username, phone, or entity ID of the chat",
+                        },
+                        limit: {
+                            type: "number",
+                            description: "Maximum number of messages to return (default: 100)",
+                        },
+                        offsetId: {
+                            type: "number",
+                            description: "Message ID to start from (for pagination)",
+                        },
+                        minId: {
+                            type: "number",
+                            description: "Minimum message ID to fetch",
+                        },
+                        maxId: {
+                            type: "number",
+                            description: "Maximum message ID to fetch",
+                        },
+                        reverse: {
+                            type: "boolean",
+                            description: "Fetch messages in reverse order (oldest first)",
+                        },
+                    },
+                    required: ["entity"],
+                },
+            },
+            {
+                name: "telegram_get_entity",
+                description: "Get information about a user, chat, or channel by username or ID.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        entity: {
+                            type: "string",
+                            description: "Username, phone, or entity ID to look up",
+                        },
+                    },
+                    required: ["entity"],
+                },
+            },
+            {
+                name: "telegram_mark_read",
+                description: "Mark messages as read in a chat.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        entity: {
+                            type: "string",
+                            description: "Username, phone, or entity ID of the chat",
+                        },
+                        maxId: {
+                            type: "number",
+                            description: "Maximum message ID to mark as read (default: latest)",
+                        },
+                    },
+                    required: ["entity"],
+                },
+            },
+            {
+                name: "telegram_delete_messages",
+                description: "Delete messages from a chat.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        entity: {
+                            type: "string",
+                            description: "Username, phone, or entity ID of the chat",
+                        },
+                        messageIds: {
+                            type: "array",
+                            items: { type: "number" },
+                            description: "Array of message IDs to delete",
+                        },
+                        revoke: {
+                            type: "boolean",
+                            description: "Delete for both parties (default: true)",
+                        },
+                    },
+                    required: ["entity", "messageIds"],
+                },
+            },
+            {
+                name: "telegram_edit_message",
+                description: "Edit a sent message.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        entity: {
+                            type: "string",
+                            description: "Username, phone, or entity ID of the chat",
+                        },
+                        messageId: {
+                            type: "number",
+                            description: "ID of the message to edit",
+                        },
+                        message: {
+                            type: "string",
+                            description: "New message text",
+                        },
+                        parseMode: {
+                            type: "string",
+                            enum: ["md", "html", ""],
+                            description: "Parse mode for formatting",
+                        },
+                    },
+                    required: ["entity", "messageId", "message"],
+                },
+            },
+            {
+                name: "telegram_forward_messages",
+                description: "Forward messages to another chat.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        fromEntity: {
+                            type: "string",
+                            description: "Source chat username or ID",
+                        },
+                        toEntity: {
+                            type: "string",
+                            description: "Destination chat username or ID",
+                        },
+                        messageIds: {
+                            type: "array",
+                            items: { type: "number" },
+                            description: "Array of message IDs to forward",
+                        },
+                    },
+                    required: ["fromEntity", "toEntity", "messageIds"],
+                },
+            },
+            // Contacts & Users
+            {
+                name: "telegram_get_contacts",
+                description: "Get list of contacts.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        limit: {
+                            type: "number",
+                            description: "Maximum number of contacts to return",
+                        },
+                    },
+                },
+            },
+            // Chats & Channels
+            {
+                name: "telegram_create_group",
+                description: "Create a new group chat.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        title: {
+                            type: "string",
+                            description: "Group title",
+                        },
+                        users: {
+                            type: "array",
+                            items: { type: "string" },
+                            description: "Array of user usernames or IDs to add",
+                        },
+                    },
+                    required: ["title", "users"],
+                },
+            },
+            {
+                name: "telegram_get_participants",
+                description: "Get participants of a group or channel.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        entity: {
+                            type: "string",
+                            description: "Group/channel username or ID",
+                        },
+                        limit: {
+                            type: "number",
+                            description: "Maximum number of participants to return",
+                        },
+                    },
+                    required: ["entity"],
+                },
+            },
+        ],
+    };
+});
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        switch (name) {
+            // ==================
+            // Connection
+            // ==================
+            case "telegram_connect": {
+                const apiId = parseInt(process.env.TELEGRAM_API_ID || "0");
+                const apiHash = process.env.TELEGRAM_API_HASH;
+                if (!apiId || !apiHash) {
+                    throw new Error("TELEGRAM_API_ID and TELEGRAM_API_HASH environment variables required. Get them from https://my.telegram.org/apps");
+                }
+                // Use provided session or load saved one
+                const savedSession = args?.sessionString || await loadSession();
+                const session = new StringSession(savedSession);
+                client = new TelegramClient(session, apiId, apiHash, {
+                    connectionRetries: 5,
+                });
+                const phoneNumber = args?.phoneNumber;
+                const code = args?.code;
+                const password = args?.password;
+                // Start the client with auth options
+                const startOptions = {
+                    onError: (err) => console.error("Telegram auth error:", err),
+                };
+                if (phoneNumber) {
+                    startOptions.phoneNumber = async () => phoneNumber;
+                }
+                if (code) {
+                    startOptions.phoneCode = async () => code;
+                }
+                if (password) {
+                    startOptions.password = async () => password;
+                }
+                await client.start(startOptions);
+                // Save session for future use
+                sessionString = client.session.save();
+                await saveSession(sessionString);
+                const me = await client.getMe();
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                success: true,
+                                message: "Connected to Telegram",
+                                user: formatEntity(me),
+                                sessionString: sessionString,
+                            }, null, 2),
+                        }],
+                };
+            }
+            case "telegram_disconnect": {
+                if (client) {
+                    await client.disconnect();
+                    client = null;
+                    sessionString = "";
+                }
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({ success: true, message: "Disconnected from Telegram" }),
+                        }],
+                };
+            }
+            case "telegram_get_session": {
+                if (!sessionString && existsSync(SESSION_FILE)) {
+                    sessionString = await loadSession();
+                }
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({ sessionString: sessionString || null }),
+                        }],
+                };
+            }
+            case "telegram_get_me": {
+                const c = await getClient();
+                const me = await c.getMe();
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify(formatEntity(me), null, 2),
+                        }],
+                };
+            }
+            case "telegram_restart": {
+                const serviceName = args?.serviceName || "telegram-mcp";
+                try {
+                    // Restart the systemd service
+                    execSync(`sudo systemctl restart ${serviceName}`, {
+                        encoding: "utf-8",
+                        timeout: 30000,
+                    });
+                    return {
+                        content: [{
+                                type: "text",
+                                text: JSON.stringify({
+                                    success: true,
+                                    message: `Systemd service '${serviceName}' restarted successfully`,
+                                    serviceName,
+                                }, null, 2),
+                            }],
+                    };
+                }
+                catch (error) {
+                    // Check if systemctl is available (not on macOS)
+                    if (error.message.includes("systemctl: command not found")) {
+                        return {
+                            content: [{
+                                    type: "text",
+                                    text: JSON.stringify({
+                                        error: true,
+                                        message: "systemctl not found. This command is only available on Linux systems with systemd.",
+                                        hint: "On macOS, use 'brew services restart' or manual process management.",
+                                    }, null, 2),
+                                }],
+                            isError: true,
+                        };
+                    }
+                    throw error;
+                }
+            }
+            // ==================
+            // Messaging
+            // ==================
+            case "telegram_send_message": {
+                if (!args?.entity || !args?.message) {
+                    throw new Error("entity and message are required");
+                }
+                const c = await getClient();
+                const entity = await c.getInputEntity(args.entity);
+                const result = await c.sendMessage(entity, {
+                    message: args.message,
+                    parseMode: args.parseMode,
+                    replyTo: args.replyTo,
+                });
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                success: true,
+                                message: formatMessage(result),
+                            }, null, 2),
+                        }],
+                };
+            }
+            case "telegram_get_dialogs": {
+                const c = await getClient();
+                const limit = args?.limit || 100;
+                const dialogs = await c.getDialogs({ limit });
+                const formatted = dialogs.map((d) => ({
+                    id: d.id?.toString(),
+                    name: d.name,
+                    unreadCount: d.unreadCount,
+                    archived: d.archived,
+                    pinned: d.pinned,
+                    entity: formatEntity(d.entity),
+                }));
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify(formatted, null, 2),
+                        }],
+                };
+            }
+            case "telegram_get_messages": {
+                if (!args?.entity) {
+                    throw new Error("entity is required");
+                }
+                const c = await getClient();
+                const entity = await c.getInputEntity(args.entity);
+                const messages = await c.getMessages(entity, {
+                    limit: args.limit || 100,
+                    offsetId: args.offsetId,
+                    minId: args.minId,
+                    maxId: args.maxId,
+                    reverse: args.reverse,
+                });
+                const formatted = messages.map(formatMessage);
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                total: messages.total,
+                                messages: formatted,
+                            }, null, 2),
+                        }],
+                };
+            }
+            case "telegram_get_entity": {
+                if (!args?.entity) {
+                    throw new Error("entity is required");
+                }
+                const c = await getClient();
+                const entity = await c.getEntity(args.entity);
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify(formatEntity(entity), null, 2),
+                        }],
+                };
+            }
+            case "telegram_mark_read": {
+                if (!args?.entity) {
+                    throw new Error("entity is required");
+                }
+                const c = await getClient();
+                const entity = await c.getInputEntity(args.entity);
+                await c.invoke(new Api.messages.ReadHistory({
+                    peer: entity,
+                    maxId: args.maxId || 0,
+                }));
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({ success: true, message: "Messages marked as read" }),
+                        }],
+                };
+            }
+            case "telegram_delete_messages": {
+                if (!args?.entity || !args?.messageIds) {
+                    throw new Error("entity and messageIds are required");
+                }
+                const c = await getClient();
+                const entity = await c.getInputEntity(args.entity);
+                await c.deleteMessages(entity, args.messageIds, { revoke: args.revoke !== false });
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({ success: true, message: "Messages deleted" }),
+                        }],
+                };
+            }
+            case "telegram_edit_message": {
+                if (!args?.entity || !args?.messageId || !args?.message) {
+                    throw new Error("entity, messageId, and message are required");
+                }
+                const c = await getClient();
+                const entity = await c.getInputEntity(args.entity);
+                const result = await c.editMessage(entity, {
+                    message: args.messageId,
+                    text: args.message,
+                    parseMode: args.parseMode,
+                });
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                success: true,
+                                message: formatMessage(result),
+                            }, null, 2),
+                        }],
+                };
+            }
+            case "telegram_forward_messages": {
+                if (!args?.fromEntity || !args?.toEntity || !args?.messageIds) {
+                    throw new Error("fromEntity, toEntity, and messageIds are required");
+                }
+                const c = await getClient();
+                const fromEntity = await c.getInputEntity(args.fromEntity);
+                const toEntity = await c.getInputEntity(args.toEntity);
+                const result = await c.forwardMessages(toEntity, {
+                    messages: args.messageIds,
+                    fromPeer: fromEntity,
+                });
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                success: true,
+                                forwarded: result.length,
+                            }, null, 2),
+                        }],
+                };
+            }
+            // ==================
+            // Contacts
+            // ==================
+            case "telegram_get_contacts": {
+                const c = await getClient();
+                const result = await c.invoke(new Api.contacts.GetContacts({
+                    hash: bigInt(0),
+                }));
+                const contacts = result.users?.map(formatEntity) || [];
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify(contacts, null, 2),
+                        }],
+                };
+            }
+            // ==================
+            // Groups & Channels
+            // ==================
+            case "telegram_create_group": {
+                if (!args?.title || !args?.users) {
+                    throw new Error("title and users are required");
+                }
+                const c = await getClient();
+                const users = await Promise.all(args.users.map((u) => c.getInputEntity(u)));
+                const result = await c.invoke(new Api.messages.CreateChat({
+                    users: users,
+                    title: args.title,
+                }));
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                success: true,
+                                chat: formatEntity(result.chats?.[0]),
+                            }, null, 2),
+                        }],
+                };
+            }
+            case "telegram_get_participants": {
+                if (!args?.entity) {
+                    throw new Error("entity is required");
+                }
+                const c = await getClient();
+                const entity = await c.getInputEntity(args.entity);
+                const result = await c.invoke(new Api.channels.GetParticipants({
+                    channel: entity,
+                    filter: new Api.ChannelParticipantsRecent(),
+                    limit: args.limit || 100,
+                    offset: 0,
+                }));
+                const participants = result.participants?.map((p) => ({
+                    userId: p.userId?.toString(),
+                    date: p.date ? new Date(p.date * 1000).toISOString() : null,
+                    className: p.className,
+                })) || [];
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                total: result.count,
+                                participants,
+                            }, null, 2),
+                        }],
+                };
+            }
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    }
+    catch (error) {
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        error: true,
+                        message: error.message,
+                        stack: error.stack,
+                    }, null, 2),
+                }],
+            isError: true,
+        };
+    }
+});
+// ==============
+// Start Server
+// ==============
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Telegram MCP server running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map