@overpod/mcp-telegram 1.22.0 → 1.24.0

package/README.md

@@ -130,6 +130,31 @@ mcp-telegram          # run server
 mcp-telegram login    # QR login
 ```
 
+### Pre-built binary (no runtime needed)
+
+Download from [Releases](https://github.com/overpod/mcp-telegram/releases) — standalone single-file binaries, zero dependencies:
+
+| Platform | Server | Login CLI |
+|----------|--------|-----------|
+| Linux x64 | `mcp-telegram-linux-x64` | `mcp-telegram-login-linux-x64` |
+| Linux ARM64 | `mcp-telegram-linux-arm64` | `mcp-telegram-login-linux-arm64` |
+| macOS x64 | `mcp-telegram-darwin-x64` | `mcp-telegram-login-darwin-x64` |
+| macOS ARM64 | `mcp-telegram-darwin-arm64` | `mcp-telegram-login-darwin-arm64` |
+| Windows x64 | `mcp-telegram-windows-x64.exe` | `mcp-telegram-login-windows-x64.exe` |
+
+```bash
+# Download (example for Linux x64)
+curl -L -o mcp-telegram https://github.com/overpod/mcp-telegram/releases/latest/download/mcp-telegram-linux-x64
+curl -L -o mcp-telegram-login https://github.com/overpod/mcp-telegram/releases/latest/download/mcp-telegram-login-linux-x64
+chmod +x mcp-telegram mcp-telegram-login
+
+# Login
+TELEGRAM_API_ID=YOUR_ID TELEGRAM_API_HASH=YOUR_HASH ./mcp-telegram-login
+
+# Run
+./mcp-telegram
+```
+
 ### From source
 
 ```bash
@@ -208,6 +233,24 @@ claude mcp add telegram -s user \
 
 > **Note**: No terminal required! Login works entirely through Claude Desktop.
 
+### Claude Desktop (Binary)
+
+Same setup, but using the pre-built binary instead of npx:
+
+```json
+{
+  "mcpServers": {
+    "telegram": {
+      "command": "/path/to/mcp-telegram",
+      "env": {
+        "TELEGRAM_API_ID": "YOUR_ID",
+        "TELEGRAM_API_HASH": "YOUR_HASH"
+      }
+    }
+  }
+}
+```
+
 ### Claude Desktop (Docker)
 
 1. Login via terminal first (see [Docker](#docker) section above).

package/dist/telegram-client.d.ts

@@ -325,4 +325,75 @@ export declare class TelegramService {
         title?: string;
     }): Promise<void>;
     removeAdmin(chatId: string, userId: string): Promise<void>;
+    unblockUser(userId: string): Promise<void>;
+    muteChat(chatId: string, muteUntil: number): Promise<void>;
+    exportInviteLink(chatId: string, options?: {
+        expireDate?: number;
+        usageLimit?: number;
+        requestNeeded?: boolean;
+        title?: string;
+    }): Promise<string>;
+    getInviteLinks(chatId: string, limit?: number, adminId?: string): Promise<Array<{
+        link: string;
+        title?: string;
+        expired: boolean;
+        revoked: boolean;
+        usageCount: number;
+    }>>;
+    revokeInviteLink(chatId: string, link: string): Promise<void>;
+    getChatFolders(): Promise<Array<{
+        id: number;
+        title: string;
+        emoticon?: string;
+        pinnedCount: number;
+        includeCount: number;
+    }>>;
+    setAutoDelete(chatId: string, period: number): Promise<void>;
+    getActiveSessions(): Promise<Array<{
+        hash: string;
+        device: string;
+        platform: string;
+        appName: string;
+        appVersion: string;
+        ip: string;
+        country: string;
+        dateActive: string;
+        current: boolean;
+    }>>;
+    terminateSession(hash: string): Promise<void>;
+    terminateAllOtherSessions(): Promise<void>;
+    private static PRIVACY_KEYS;
+    setPrivacy(setting: string, rule: "everyone" | "contacts" | "nobody", allowUsers?: string[], disallowUsers?: string[]): Promise<void>;
+    updateProfile(options: {
+        firstName?: string;
+        lastName?: string;
+        bio?: string;
+    }): Promise<void>;
+    updateUsername(username: string): Promise<void>;
+    getStickerSet(shortName: string): Promise<{
+        title: string;
+        shortName: string;
+        count: number;
+        stickers: Array<{
+            id: string;
+            accessHash: string;
+            emoji: string;
+        }>;
+    }>;
+    searchStickerSets(query: string): Promise<Array<{
+        title: string;
+        shortName: string;
+        count: number;
+    }>>;
+    getInstalledStickerSets(): Promise<Array<{
+        title: string;
+        shortName: string;
+        count: number;
+    }>>;
+    sendSticker(chatId: string, stickerSetShortName: string, stickerIndex: number, replyTo?: number): Promise<Api.Message | Api.UpdateShortSentMessage | undefined>;
+    getRecentStickers(): Promise<Array<{
+        id: string;
+        accessHash: string;
+        emoji: string;
+    }>>;
 }

package/dist/telegram-client.js

@@ -1637,4 +1637,311 @@ export class TelegramService {
             rank: "",
         }));
     }
+    // ── New tools: feature parity ──────────────────────────────────────
+    async unblockUser(userId) {
+        if (!this.client || !this.connected)
+            throw new Error(NOT_CONNECTED_ERROR);
+        const entity = await this.client.getInputEntity(userId);
+        await this.client.invoke(new Api.contacts.Unblock({ id: entity }));
+    }
+    async muteChat(chatId, muteUntil) {
+        if (!this.client || !this.connected)
+            throw new Error(NOT_CONNECTED_ERROR);
+        const resolved = await this.resolvePeer(chatId);
+        const peer = await this.client.getInputEntity(resolved);
+        await this.client.invoke(new Api.account.UpdateNotifySettings({
+            peer: new Api.InputNotifyPeer({ peer }),
+            settings: new Api.InputPeerNotifySettings({ muteUntil }),
+        }));
+    }
+    async exportInviteLink(chatId, options) {
+        if (!this.client || !this.connected)
+            throw new Error(NOT_CONNECTED_ERROR);
+        const resolved = await this.resolvePeer(chatId);
+        const peer = await this.client.getInputEntity(resolved);
+        const result = await this.client.invoke(new Api.messages.ExportChatInvite({
+            peer,
+            expireDate: options?.expireDate,
+            usageLimit: options?.usageLimit,
+            requestNeeded: options?.requestNeeded,
+            title: options?.title,
+        }));
+        if (result instanceof Api.ChatInviteExported) {
+            return result.link;
+        }
+        throw new Error("Failed to export invite link");
+    }
+    async getInviteLinks(chatId, limit = 20, adminId) {
+        if (!this.client || !this.connected)
+            throw new Error(NOT_CONNECTED_ERROR);
+        const resolved = await this.resolvePeer(chatId);
+        const peer = await this.client.getInputEntity(resolved);
+        const admin = adminId ? await this.client.getInputEntity(await this.resolvePeer(adminId)) : new Api.InputUserSelf();
+        const result = await this.client.invoke(new Api.messages.GetExportedChatInvites({
+            peer,
+            adminId: admin,
+            limit,
+        }));
+        return result.invites
+            .filter((inv) => inv instanceof Api.ChatInviteExported)
+            .map((inv) => {
+            const expiredByDate = inv.expireDate ? inv.expireDate < Math.floor(Date.now() / 1000) : false;
+            const expiredByUsage = inv.usageLimit !== undefined && inv.usage !== undefined ? inv.usage >= inv.usageLimit : false;
+            return {
+                link: inv.link,
+                title: inv.title,
+                expired: expiredByDate || expiredByUsage,
+                revoked: inv.revoked ?? false,
+                usageCount: inv.usage ?? 0,
+            };
+        });
+    }
+    async revokeInviteLink(chatId, link) {
+        if (!this.client || !this.connected)
+            throw new Error(NOT_CONNECTED_ERROR);
+        const resolved = await this.resolvePeer(chatId);
+        const peer = await this.client.getInputEntity(resolved);
+        await this.client.invoke(new Api.messages.EditExportedChatInvite({
+            peer,
+            link,
+            revoked: true,
+        }));
+    }
+    async getChatFolders() {
+        if (!this.client || !this.connected)
+            throw new Error(NOT_CONNECTED_ERROR);
+        const result = await this.client.invoke(new Api.messages.GetDialogFilters());
+        const filters = "filters" in result ? result.filters : [];
+        return filters
+            .filter((f) => f instanceof Api.DialogFilter)
+            .map((f) => ({
+            id: f.id,
+            title: typeof f.title === "string" ? f.title : f.title.text,
+            emoticon: f.emoticon,
+            pinnedCount: f.pinnedPeers?.length ?? 0,
+            includeCount: f.includePeers?.length ?? 0,
+        }));
+    }
+    async setAutoDelete(chatId, period) {
+        if (!this.client || !this.connected)
+            throw new Error(NOT_CONNECTED_ERROR);
+        const resolved = await this.resolvePeer(chatId);
+        const peer = await this.client.getInputEntity(resolved);
+        await this.client.invoke(new Api.messages.SetHistoryTTL({ peer, period }));
+    }
+    async getActiveSessions() {
+        if (!this.client || !this.connected)
+            throw new Error(NOT_CONNECTED_ERROR);
+        const result = await this.client.invoke(new Api.account.GetAuthorizations());
+        return result.authorizations.map((a) => ({
+            hash: a.hash.toString(),
+            device: a.deviceModel,
+            platform: a.platform,
+            appName: a.appName,
+            appVersion: a.appVersion,
+            ip: a.ip,
+            country: a.country,
+            dateActive: new Date(a.dateActive * 1000).toISOString(),
+            current: a.current ?? false,
+        }));
+    }
+    async terminateSession(hash) {
+        if (!this.client || !this.connected)
+            throw new Error(NOT_CONNECTED_ERROR);
+        await this.client.invoke(new Api.account.ResetAuthorization({ hash: bigInt(hash) }));
+    }
+    async terminateAllOtherSessions() {
+        if (!this.client || !this.connected)
+            throw new Error(NOT_CONNECTED_ERROR);
+        await this.client.invoke(new Api.auth.ResetAuthorizations());
+    }
+    static PRIVACY_KEYS = {
+        phone_number: () => new Api.InputPrivacyKeyPhoneNumber(),
+        last_seen: () => new Api.InputPrivacyKeyStatusTimestamp(),
+        profile_photo: () => new Api.InputPrivacyKeyProfilePhoto(),
+        forwards: () => new Api.InputPrivacyKeyForwards(),
+        calls: () => new Api.InputPrivacyKeyPhoneCall(),
+        groups: () => new Api.InputPrivacyKeyChatInvite(),
+        bio: () => new Api.InputPrivacyKeyAbout(),
+    };
+    async setPrivacy(setting, rule, allowUsers, disallowUsers) {
+        if (!this.client || !this.connected)
+            throw new Error(NOT_CONNECTED_ERROR);
+        const keyFactory = TelegramService.PRIVACY_KEYS[setting];
+        if (!keyFactory)
+            throw new Error(`Unknown privacy setting: ${setting}. Valid: ${Object.keys(TelegramService.PRIVACY_KEYS).join(", ")}`);
+        const rules = [];
+        // Exceptions must come before the general rule so they are not shadowed
+        if (disallowUsers?.length) {
+            const users = [];
+            const invalid = [];
+            for (const u of disallowUsers) {
+                const inputEntity = await this.client.getInputEntity(u);
+                if (inputEntity instanceof Api.InputPeerUser) {
+                    users.push(new Api.InputUser({ userId: inputEntity.userId, accessHash: inputEntity.accessHash }));
+                }
+                else {
+                    invalid.push(u);
+                }
+            }
+            if (invalid.length > 0) {
+                throw new Error(`disallowUsers entries are not valid users: ${invalid.join(", ")}`);
+            }
+            if (users.length > 0) {
+                rules.push(new Api.InputPrivacyValueDisallowUsers({ users }));
+            }
+        }
+        if (allowUsers?.length) {
+            const users = [];
+            const invalid = [];
+            for (const u of allowUsers) {
+                const inputEntity = await this.client.getInputEntity(u);
+                if (inputEntity instanceof Api.InputPeerUser) {
+                    users.push(new Api.InputUser({ userId: inputEntity.userId, accessHash: inputEntity.accessHash }));
+                }
+                else {
+                    invalid.push(u);
+                }
+            }
+            if (invalid.length > 0) {
+                throw new Error(`allowUsers entries are not valid users: ${invalid.join(", ")}`);
+            }
+            if (users.length > 0) {
+                rules.push(new Api.InputPrivacyValueAllowUsers({ users }));
+            }
+        }
+        if (rule === "everyone")
+            rules.push(new Api.InputPrivacyValueAllowAll());
+        else if (rule === "contacts")
+            rules.push(new Api.InputPrivacyValueAllowContacts(), new Api.InputPrivacyValueDisallowAll());
+        else
+            rules.push(new Api.InputPrivacyValueDisallowAll());
+        await this.client.invoke(new Api.account.SetPrivacy({ key: keyFactory(), rules }));
+    }
+    async updateProfile(options) {
+        if (!this.client || !this.connected)
+            throw new Error(NOT_CONNECTED_ERROR);
+        await this.client.invoke(new Api.account.UpdateProfile({
+            firstName: options.firstName,
+            lastName: options.lastName,
+            about: options.bio,
+        }));
+    }
+    async updateUsername(username) {
+        if (!this.client || !this.connected)
+            throw new Error(NOT_CONNECTED_ERROR);
+        await this.client.invoke(new Api.account.UpdateUsername({ username }));
+    }
+    // ─── Stickers ──────────────────────────────────────────────
+    async getStickerSet(shortName) {
+        if (!this.client || !this.connected)
+            throw new Error(NOT_CONNECTED_ERROR);
+        const result = await this.client.invoke(new Api.messages.GetStickerSet({
+            stickerset: new Api.InputStickerSetShortName({ shortName }),
+            hash: 0,
+        }));
+        if (result instanceof Api.messages.StickerSetNotModified) {
+            throw new Error("Sticker set was not modified");
+        }
+        const set = result.set;
+        const packs = result.packs;
+        // Build emoji map: document id -> emoji
+        const emojiMap = new Map();
+        for (const pack of packs) {
+            for (const docId of pack.documents) {
+                emojiMap.set(docId.toString(), pack.emoticon);
+            }
+        }
+        return {
+            title: set.title,
+            shortName: set.shortName,
+            count: set.count,
+            stickers: result.documents.map((doc) => ({
+                id: doc.id.toString(),
+                accessHash: doc.accessHash.toString(),
+                emoji: emojiMap.get(doc.id.toString()) || "",
+            })),
+        };
+    }
+    async searchStickerSets(query) {
+        if (!this.client || !this.connected)
+            throw new Error(NOT_CONNECTED_ERROR);
+        const result = await this.client.invoke(new Api.messages.SearchStickerSets({
+            q: query,
+            hash: bigInt(0),
+        }));
+        if (result instanceof Api.messages.FoundStickerSetsNotModified) {
+            return [];
+        }
+        return result.sets.map((covered) => {
+            const set = covered.set;
+            return {
+                title: set.title,
+                shortName: set.shortName,
+                count: set.count,
+            };
+        });
+    }
+    async getInstalledStickerSets() {
+        if (!this.client || !this.connected)
+            throw new Error(NOT_CONNECTED_ERROR);
+        const result = await this.client.invoke(new Api.messages.GetAllStickers({ hash: bigInt(0) }));
+        if (result instanceof Api.messages.AllStickersNotModified) {
+            return [];
+        }
+        return result.sets.map((set) => ({
+            title: set.title,
+            shortName: set.shortName,
+            count: set.count,
+        }));
+    }
+    async sendSticker(chatId, stickerSetShortName, stickerIndex, replyTo) {
+        if (!this.client || !this.connected)
+            throw new Error(NOT_CONNECTED_ERROR);
+        return await this.rateLimiter.execute(async () => {
+            if (!Number.isInteger(stickerIndex)) {
+                throw new Error(`Sticker index must be an integer, got ${stickerIndex}`);
+            }
+            // Fetch raw sticker set to get the actual Api.Document with valid fileReference
+            const rawResult = await this.client?.invoke(new Api.messages.GetStickerSet({
+                stickerset: new Api.InputStickerSetShortName({ shortName: stickerSetShortName }),
+                hash: 0,
+            }));
+            if (!rawResult || rawResult instanceof Api.messages.StickerSetNotModified) {
+                throw new Error("Sticker set not found");
+            }
+            const stickerSet = rawResult;
+            if (stickerIndex < 0 || stickerIndex >= stickerSet.documents.length) {
+                throw new Error(`Sticker index ${stickerIndex} out of range (0-${stickerSet.documents.length - 1})`);
+            }
+            const sticker = stickerSet.documents[stickerIndex];
+            if (!(sticker instanceof Api.Document)) {
+                throw new Error("Selected sticker is not a valid document");
+            }
+            const resolved = await this.resolvePeer(chatId);
+            return await this.client?.sendFile(resolved, {
+                file: sticker,
+                ...(replyTo ? { replyTo } : {}),
+            });
+        }, `sendSticker to ${chatId}`);
+    }
+    async getRecentStickers() {
+        if (!this.client || !this.connected)
+            throw new Error(NOT_CONNECTED_ERROR);
+        const result = await this.client.invoke(new Api.messages.GetRecentStickers({ hash: bigInt(0) }));
+        if (result instanceof Api.messages.RecentStickersNotModified) {
+            return [];
+        }
+        const emojiMap = new Map();
+        for (const pack of result.packs) {
+            for (const docId of pack.documents) {
+                emojiMap.set(docId.toString(), pack.emoticon);
+            }
+        }
+        return result.stickers.map((doc) => ({
+            id: doc.id.toString(),
+            accessHash: doc.accessHash.toString(),
+            emoji: emojiMap.get(doc.id.toString()) || "",
+        }));
+    }
 }

package/dist/tools/account.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TelegramService } from "../telegram-client.js";
+export declare function registerAccountTools(server: McpServer, telegram: TelegramService): void;

package/dist/tools/account.js

@@ -0,0 +1,280 @@
+import { z } from "zod";
+import { DESTRUCTIVE, fail, ok, READ_ONLY, requireConnection, sanitize, WRITE } from "./shared.js";
+const MUTE_FOREVER_UNTIL = 2147483647; // max 32-bit signed int
+export function registerAccountTools(server, telegram) {
+    server.registerTool("telegram-mute-chat", {
+        description: "Mute or unmute notifications for a Telegram chat. Set muted=true to mute (optionally with duration in seconds), muted=false to unmute",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            muted: z.boolean().describe("true to mute, false to unmute"),
+            duration: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("Mute duration in seconds (only when muted=true, must be > 0). Omit to mute forever"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, muted, duration }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            let muteUntil;
+            if (!muted) {
+                muteUntil = 0;
+            }
+            else if (duration !== undefined && duration > 0) {
+                const now = Math.floor(Date.now() / 1000);
+                muteUntil = Math.min(now + duration, MUTE_FOREVER_UNTIL);
+            }
+            else {
+                muteUntil = MUTE_FOREVER_UNTIL;
+            }
+            await telegram.muteChat(chatId, muteUntil);
+            const status = !muted
+                ? "unmuted"
+                : duration !== undefined && duration > 0
+                    ? `muted for ${duration}s`
+                    : "muted forever";
+            return ok(`Chat ${chatId} ${status}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-chat-folders", {
+        description: "Get list of your Telegram chat folders (filters) with their names and chat counts",
+        inputSchema: {},
+        annotations: READ_ONLY,
+    }, async () => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const folders = await telegram.getChatFolders();
+            if (folders.length === 0)
+                return ok("No chat folders");
+            const text = folders
+                .map((f) => `[${f.id}] ${f.emoticon ? `${f.emoticon} ` : ""}${f.title} (${f.includeCount} chats, ${f.pinnedCount} pinned)`)
+                .join("\n");
+            return ok(sanitize(text));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-set-auto-delete", {
+        description: "Set auto-delete timer for messages in a chat. Common values: 86400 (1 day), 604800 (1 week), 2592000 (1 month). Use 0 to disable",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            period: z
+                .number()
+                .int()
+                .nonnegative()
+                .describe("Auto-delete period in seconds. 0 = disable. Common: 86400 (1d), 604800 (1w), 2592000 (1mo)"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, period }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.setAutoDelete(chatId, period);
+            const status = period === 0 ? "disabled" : `set to ${period}s`;
+            return ok(`Auto-delete for ${chatId} ${status}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-sessions", {
+        description: "Get list of all active Telegram sessions (logged-in devices) with device info, IP, and last active time",
+        inputSchema: {},
+        annotations: READ_ONLY,
+    }, async () => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const sessions = await telegram.getActiveSessions();
+            if (sessions.length === 0)
+                return ok("No active sessions");
+            const text = sessions
+                .map((s) => `${s.current ? "→ " : "  "}${s.device} (${s.platform}) — ${s.appName} ${s.appVersion}\n    IP: ${s.ip} (${s.country}) | Last active: ${s.dateActive}${s.current ? " [CURRENT]" : ""}\n    Hash: ${s.hash}`)
+                .join("\n\n");
+            return ok(sanitize(text));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-terminate-session", {
+        description: "Terminate a specific Telegram session by its hash, or explicitly terminate all other sessions by setting terminateAllOther=true",
+        inputSchema: {
+            sessionId: z
+                .string()
+                .optional()
+                .describe("Session hash to terminate (numeric string from get-sessions). Required when terminateAllOther is not set")
+                .refine((v) => v === undefined || /^\d+$/.test(v), { message: "sessionId must be a numeric string" }),
+            terminateAllOther: z
+                .boolean()
+                .optional()
+                .describe("Set to true to terminate all other sessions (excludes current). Cannot be combined with sessionId"),
+        },
+        annotations: DESTRUCTIVE,
+    }, async ({ sessionId, terminateAllOther }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            if (terminateAllOther) {
+                if (sessionId) {
+                    return fail(new Error("Provide either sessionId or terminateAllOther=true, not both"));
+                }
+                await telegram.terminateAllOtherSessions();
+                return ok("All other sessions terminated");
+            }
+            if (!sessionId) {
+                return fail(new Error("Provide sessionId to terminate a specific session, or set terminateAllOther=true"));
+            }
+            await telegram.terminateSession(sessionId);
+            return ok(`Session ${sessionId} terminated`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-set-privacy", {
+        description: "Configure privacy settings for your Telegram account. Controls who can see your phone number, last seen, profile photo, etc.",
+        inputSchema: {
+            setting: z
+                .enum(["phone_number", "last_seen", "profile_photo", "forwards", "calls", "groups", "bio"])
+                .describe("Privacy setting to change"),
+            rule: z.enum(["everyone", "contacts", "nobody"]).describe("Who can see/access this"),
+            allowUsers: z.array(z.string()).optional().describe("User IDs/usernames to always allow (exceptions)"),
+            disallowUsers: z.array(z.string()).optional().describe("User IDs/usernames to always disallow (exceptions)"),
+        },
+        annotations: WRITE,
+    }, async ({ setting, rule, allowUsers, disallowUsers }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.setPrivacy(setting, rule, allowUsers, disallowUsers);
+            return ok(`Privacy: ${setting} set to "${rule}"`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-update-profile", {
+        description: "Update your Telegram profile — first name, last name, bio, or username",
+        inputSchema: {
+            firstName: z.string().optional().describe("New first name"),
+            lastName: z.string().optional().describe("New last name"),
+            bio: z.string().optional().describe("New bio/about text (max 70 chars, 300 for Premium)"),
+            username: z.string().optional().describe("New username (without @)"),
+        },
+        annotations: WRITE,
+    }, async ({ firstName, lastName, bio, username }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const updates = [];
+            if (firstName !== undefined || lastName !== undefined || bio !== undefined) {
+                await telegram.updateProfile({ firstName, lastName, bio });
+                if (firstName !== undefined)
+                    updates.push(`firstName: ${firstName}`);
+                if (lastName !== undefined)
+                    updates.push(`lastName: ${lastName}`);
+                if (bio !== undefined)
+                    updates.push(`bio: ${bio}`);
+            }
+            if (username !== undefined) {
+                const normalizedUsername = username.replace(/^@/, "");
+                await telegram.updateUsername(normalizedUsername);
+                updates.push(`username: @${normalizedUsername}`);
+            }
+            return ok(updates.length ? `Profile updated: ${updates.join(", ")}` : "No changes specified");
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-create-invite-link", {
+        description: "Create a new invite link for a group or channel",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            expireDate: z.number().optional().describe("Link expiration as Unix timestamp"),
+            memberLimit: z.number().optional().describe("Max number of users who can join via this link"),
+            requestApproval: z.boolean().optional().describe("Require admin approval to join"),
+            title: z.string().optional().describe("Label for the invite link (only visible to admins)"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, expireDate, memberLimit, requestApproval, title }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const link = await telegram.exportInviteLink(chatId, {
+                expireDate,
+                usageLimit: memberLimit,
+                requestNeeded: requestApproval,
+                title,
+            });
+            return ok(`Invite link created: ${link}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-invite-links", {
+        description: "Get list of invite links for a group or channel. By default returns links created by the current account; pass adminId to query another admin's links",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            limit: z.number().default(20).describe("Max links to return"),
+            adminId: z
+                .string()
+                .optional()
+                .describe("Admin user ID or username to list links for (default: current account)"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chatId, limit, adminId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const links = await telegram.getInviteLinks(chatId, limit, adminId);
+            if (links.length === 0)
+                return ok("No invite links");
+            const text = links
+                .map((l) => `${l.link}${l.title ? ` (${l.title})` : ""} — ${l.usageCount} uses${l.expired ? " [EXPIRED]" : ""}${l.revoked ? " [REVOKED]" : ""}`)
+                .join("\n");
+            return ok(sanitize(text));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-revoke-invite-link", {
+        description: "Revoke an invite link for a group or channel",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            link: z.string().describe("The invite link to revoke"),
+        },
+        annotations: DESTRUCTIVE,
+    }, async ({ chatId, link }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.revokeInviteLink(chatId, link);
+            return ok(`Invite link revoked: ${link}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+}

package/dist/tools/contacts.js

@@ -116,6 +116,22 @@ export function registerContactTools(server, telegram) {
             return fail(e);
         }
     });
+    server.registerTool("telegram-unblock-user", {
+        description: "Unblock a previously blocked Telegram user",
+        inputSchema: { userId: z.string().describe("User ID or username to unblock") },
+        annotations: WRITE,
+    }, async ({ userId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.unblockUser(userId);
+            return ok(`User unblocked: ${userId}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
     server.registerTool("telegram-report-spam", {
         description: "Report a chat as spam to Telegram",
         inputSchema: { chatId: z.string().describe("Chat ID or username to report") },

package/dist/tools/index.js

@@ -1,3 +1,4 @@
+import { registerAccountTools } from "./account.js";
 import { registerAuthTools } from "./auth.js";
 import { registerChatTools } from "./chats.js";
 import { registerContactTools } from "./contacts.js";
@@ -5,6 +6,7 @@ import { registerExtraTools } from "./extras.js";
 import { registerMediaTools } from "./media.js";
 import { registerMessageTools } from "./messages.js";
 import { registerReactionTools } from "./reactions.js";
+import { registerStickerTools } from "./stickers.js";
 export function registerTools(server, telegram) {
     registerAuthTools(server, telegram);
     registerMessageTools(server, telegram);
@@ -13,4 +15,6 @@ export function registerTools(server, telegram) {
     registerContactTools(server, telegram);
     registerReactionTools(server, telegram);
     registerExtraTools(server, telegram);
+    registerAccountTools(server, telegram);
+    registerStickerTools(server, telegram);
 }

package/dist/tools/stickers.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TelegramService } from "../telegram-client.js";
+export declare function registerStickerTools(server: McpServer, telegram: TelegramService): void;

package/dist/tools/stickers.js

@@ -0,0 +1,139 @@
+import { z } from "zod";
+import { fail, ok, READ_ONLY, requireConnection, sanitize, WRITE } from "./shared.js";
+export function registerStickerTools(server, telegram) {
+    server.registerTool("telegram-get-sticker-set", {
+        description: "Get all stickers from a sticker set by its short name. Returns each sticker with index and emoji. Use the index with telegram-send-sticker to send a specific sticker",
+        inputSchema: {
+            shortName: z
+                .string()
+                .describe("Short name of the sticker set (e.g. 'AnimatedEmojis', 'HotCherry'). Find names via telegram-search-sticker-sets or from t.me/addstickers/<shortName> links"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ shortName }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const set = await telegram.getStickerSet(shortName);
+            const lines = [];
+            lines.push(`📦 ${set.title} (${set.shortName})`);
+            lines.push(`${set.count} stickers`);
+            lines.push("");
+            for (let i = 0; i < set.stickers.length; i++) {
+                const s = set.stickers[i];
+                lines.push(`[${i}] ${s.emoji}`);
+            }
+            lines.push("");
+            lines.push(`Send a sticker: telegram-send-sticker(chatId, stickerSet="${set.shortName}", index=N)`);
+            return ok(sanitize(lines.join("\n")));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-search-sticker-sets", {
+        description: "Search for sticker sets by name or keyword. Returns matching sticker pack names that can be used with telegram-get-sticker-set",
+        inputSchema: {
+            query: z.string().describe("Search query (e.g. 'cat', 'love', 'pepe', 'anime')"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ query }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const sets = await telegram.searchStickerSets(query);
+            if (sets.length === 0) {
+                return ok(`No sticker sets found for "${query}". Try different keywords.`);
+            }
+            const lines = [];
+            lines.push(`Found ${sets.length} sticker set(s) for "${query}":\n`);
+            for (const set of sets) {
+                const flags = "";
+                lines.push(`• ${set.title}${flags} — ${set.count} stickers`);
+                lines.push(`  Short name: ${set.shortName}`);
+            }
+            lines.push("");
+            lines.push("Use telegram-get-sticker-set(shortName) to see individual stickers.");
+            return ok(sanitize(lines.join("\n")));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-installed-stickers", {
+        description: "List all sticker sets installed by the user. Returns pack names and short names for use with other sticker tools",
+        inputSchema: {},
+        annotations: READ_ONLY,
+    }, async () => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const sets = await telegram.getInstalledStickerSets();
+            if (sets.length === 0) {
+                return ok("No sticker sets installed.");
+            }
+            const lines = [];
+            lines.push(`${sets.length} installed sticker set(s):\n`);
+            for (const set of sets) {
+                const flags = "";
+                lines.push(`• ${set.title}${flags} — ${set.count} stickers`);
+                lines.push(`  Short name: ${set.shortName}`);
+            }
+            return ok(sanitize(lines.join("\n")));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-send-sticker", {
+        description: "Send a sticker from a sticker set to a chat. First use telegram-get-sticker-set to browse available stickers and find the index",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+            stickerSet: z.string().describe("Short name of the sticker set (e.g. 'HotCherry')"),
+            index: z
+                .number()
+                .int()
+                .nonnegative()
+                .describe("Index of the sticker in the set (0-based, get from telegram-get-sticker-set)"),
+            replyTo: z.number().int().optional().describe("Message ID to reply to"),
+        },
+        annotations: WRITE,
+    }, async ({ chatId, stickerSet, index, replyTo }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            await telegram.sendSticker(chatId, stickerSet, index, replyTo);
+            return ok(`Sticker sent from "${stickerSet}" [${index}] to ${chatId}`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("telegram-get-recent-stickers", {
+        description: "Get recently used stickers. Returns each sticker with its list index and associated emoji",
+        inputSchema: {},
+        annotations: READ_ONLY,
+    }, async () => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const stickers = await telegram.getRecentStickers();
+            if (stickers.length === 0) {
+                return ok("No recent stickers.");
+            }
+            const lines = [];
+            lines.push(`${stickers.length} recent sticker(s):\n`);
+            for (let i = 0; i < stickers.length; i++) {
+                lines.push(`[${i}] ${stickers[i].emoji}`);
+            }
+            return ok(sanitize(lines.join("\n")));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+}

package/package.json

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