@ebowwa/mcp-telegram 0.1.4

package/src/index.ts

@@ -0,0 +1,907 @@
+#!/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: TelegramClient | null = null;
+let sessionString: string = "";
+
+// ==============
+// Helper Functions
+// ==============
+
+async function loadSession(): Promise<string> {
+  if (existsSync(SESSION_FILE)) {
+    return readFileSync(SESSION_FILE, "utf-8").trim();
+  }
+  return "";
+}
+
+async function saveSession(session: string): Promise<void> {
+  writeFileSync(SESSION_FILE, session, "utf-8");
+}
+
+async function getClient(): Promise<TelegramClient> {
+  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: any): any {
+  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: any): any {
+  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 as string) || await loadSession();
+        const session = new StringSession(savedSession);
+
+        client = new TelegramClient(session, apiId, apiHash, {
+          connectionRetries: 5,
+        });
+
+        const phoneNumber = args?.phoneNumber as string | undefined;
+        const code = args?.code as string | undefined;
+        const password = args?.password as string | undefined;
+
+        // Start the client with auth options
+        const startOptions: any = {
+          onError: (err: Error) => 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() as unknown as string;
+        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 as string) || "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: any) {
+          // 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 as string);
+
+        const result = await c.sendMessage(entity, {
+          message: args.message as string,
+          parseMode: args.parseMode as any,
+          replyTo: args.replyTo as number,
+        });
+
+        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 as number) || 100;
+
+        const dialogs = await c.getDialogs({ limit });
+
+        const formatted = dialogs.map((d: any) => ({
+          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 as string);
+
+        const messages = await c.getMessages(entity, {
+          limit: (args.limit as number) || 100,
+          offsetId: args.offsetId as number,
+          minId: args.minId as number,
+          maxId: args.maxId as number,
+          reverse: args.reverse as boolean,
+        });
+
+        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 as string);
+        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 as string);
+
+        await c.invoke(
+          new Api.messages.ReadHistory({
+            peer: entity,
+            maxId: (args.maxId as number) || 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 as string);
+
+        await c.deleteMessages(
+          entity,
+          args.messageIds as number[],
+          { 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 as string);
+
+        const result = await c.editMessage(entity, {
+          message: args.messageId as number,
+          text: args.message as string,
+          parseMode: args.parseMode as any,
+        });
+
+        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 as string);
+        const toEntity = await c.getInputEntity(args.toEntity as string);
+
+        const result = await c.forwardMessages(toEntity, {
+          messages: args.messageIds as number[],
+          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 as any).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 as string[]).map((u: string) => c.getInputEntity(u))
+        );
+
+        const result = await c.invoke(
+          new Api.messages.CreateChat({
+            users: users,
+            title: args.title as string,
+          })
+        );
+
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              success: true,
+              chat: formatEntity((result as any).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 as string);
+
+        const result = await c.invoke(
+          new Api.channels.GetParticipants({
+            channel: entity,
+            filter: new Api.ChannelParticipantsRecent(),
+            limit: (args.limit as number) || 100,
+            offset: 0,
+          })
+        );
+
+        const participants = (result as any).participants?.map((p: any) => ({
+          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 as any).count,
+              participants,
+            }, null, 2),
+          }],
+        };
+      }
+
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+  } catch (error: any) {
+    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);
+});