@overpod/mcp-telegram 1.23.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

@@ -370,4 +370,30 @@ export declare class TelegramService {
         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

@@ -1832,4 +1832,116 @@ export class TelegramService {
             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/index.js

@@ -6,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);
@@ -15,4 +16,5 @@ export function registerTools(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.23.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",