telegram-notifier-mcp 1.0.0 → 1.1.0

package/README.md

@@ -1,14 +1,10 @@
 # Telegram Notifier MCP Server
 
-A one-way notification [MCP](https://modelcontextprotocol.io/) server that lets an LLM send messages and files to a user via a Telegram bot. No external HTTP or Telegram libraries — just the native `fetch` API and the official MCP SDK.
+An [MCP](https://modelcontextprotocol.io/) server that lets an LLM send messages and files to a user via a Telegram bot, and read incoming messages. No external HTTP or Telegram libraries — just the native `fetch` API and the official MCP SDK.
 
-## Prerequisites
+## Quick Start
 
-- Node.js 18+
-- A Telegram bot token (from [@BotFather](https://t.me/BotFather))
-- Your Telegram chat ID
-
-## Setup
+No cloning or building required — just add the config to your MCP client.
 
 ### 1. Create a Telegram Bot
 
@@ -27,29 +23,9 @@ A one-way notification [MCP](https://modelcontextprotocol.io/) server that lets
 
 > **Tip:** For group chats, add the bot to the group, send a message, and check the same URL. Group chat IDs are negative numbers (e.g., `-1001234567890`).
 
-### 3. Install and Build
-
-```bash
-git clone <your-repo-url>
-cd telegram-notifier-mcp
-npm install
-npm run build
-```
-
-## Configuration
-
-The server uses two environment variables:
-
-| Variable | Required | Description |
-|---|---|---|
-| `TELEGRAM_BOT_TOKEN` | Yes | Bot token from @BotFather |
-| `TELEGRAM_CHAT_ID` | No | Default chat ID. Can be overridden per-tool call via the `chatId` parameter. |
-
-The server will exit with an error if `TELEGRAM_BOT_TOKEN` is not set. If `TELEGRAM_CHAT_ID` is not set, you must pass `chatId` to every tool call.
+### 3. Add to Your MCP Client
 
-## Adding to Your MCP Client
-
-### Claude Desktop
+#### Claude Desktop
 
 Add this to your Claude Desktop config file:
 
@@ -60,8 +36,8 @@ Add this to your Claude Desktop config file:
 {
   "mcpServers": {
     "telegram-notifier": {
-      "command": "node",
-      "args": ["/absolute/path/to/telegram-notifier-mcp/build/index.js"],
+      "command": "npx",
+      "args": ["telegram-notifier-mcp"],
       "env": {
         "TELEGRAM_BOT_TOKEN": "your-bot-token-here",
         "TELEGRAM_CHAT_ID": "your-chat-id-here"
@@ -71,16 +47,16 @@ Add this to your Claude Desktop config file:
 }
 ```
 
-### Claude Code
+#### Claude Code
 
-Add to your project's `.mcp.json` or global `~/.claude/claude_code_config.json`:
+Add to your project's `.mcp.json` or `~/.claude.json`:
 
 ```json
 {
   "mcpServers": {
     "telegram-notifier": {
-      "command": "node",
-      "args": ["/absolute/path/to/telegram-notifier-mcp/build/index.js"],
+      "command": "npx",
+      "args": ["telegram-notifier-mcp"],
       "env": {
         "TELEGRAM_BOT_TOKEN": "your-bot-token-here",
         "TELEGRAM_CHAT_ID": "your-chat-id-here"
@@ -90,6 +66,19 @@ Add to your project's `.mcp.json` or global `~/.claude/claude_code_config.json`:
 }
 ```
 
+That's it — your LLM can now send you Telegram notifications.
+
+## Configuration
+
+The server uses two environment variables:
+
+| Variable | Required | Description |
+|---|---|---|
+| `TELEGRAM_BOT_TOKEN` | Yes | Bot token from @BotFather |
+| `TELEGRAM_CHAT_ID` | No | Default chat ID. Can be overridden per-tool call via the `chatId` parameter. |
+
+The server will exit with an error if `TELEGRAM_BOT_TOKEN` is not set. If `TELEGRAM_CHAT_ID` is not set, you must pass `chatId` to every tool call.
+
 ## Tools
 
 ### `send_message`
@@ -151,13 +140,22 @@ Send an audio file to a Telegram chat.
 | `parseMode` | string | No | `Markdown`, `MarkdownV2`, or `HTML` |
 | `disableNotification` | boolean | No | Send silently without notification sound |
 
+### `get_updates`
+
+Check for new messages sent to the bot. Only returns messages received since the last check.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `limit` | number | No | Max messages to retrieve (1-100, default 10) |
+| `timeout` | number | No | Long-polling timeout in seconds (0-30, default 0). Set >0 to wait for new messages. |
+
 ## Testing with the MCP Inspector
 
 You can test the server interactively using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):
 
 ```bash
 TELEGRAM_BOT_TOKEN="your-token" TELEGRAM_CHAT_ID="your-chat-id" \
-  npx @modelcontextprotocol/inspector node build/index.js
+  npx @modelcontextprotocol/inspector npx telegram-notifier-mcp
 ```
 
 This opens a browser UI where you can invoke each tool and see the results.
@@ -183,6 +181,11 @@ Telegram enforces a **50 MB** limit for file uploads via the Bot API. The server
 ## Development
 
 ```bash
+git clone https://github.com/AdeshAtole/telegram-notifier-mcp
+cd telegram-notifier-mcp
+npm install
+npm run build
+
 # Watch mode — rebuilds on file changes
 npm run dev
 ```

package/build/index.js

@@ -2,8 +2,9 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { readFile, stat } from "node:fs/promises";
-import { basename } from "node:path";
+import { readFile, writeFile, stat, mkdir } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { homedir } from "node:os";
 // ---------------------------------------------------------------------------
 // Config
 // ---------------------------------------------------------------------------
@@ -16,6 +17,57 @@ if (!TELEGRAM_BOT_TOKEN) {
 }
 const TELEGRAM_API = `https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}`;
 const MAX_FILE_SIZE = 50 * 1024 * 1024; // 50 MB
+// Persist the getUpdates offset to disk so we don't re-fetch old messages after restart
+const OFFSET_DIR = join(homedir(), ".telegram-notifier-mcp");
+const OFFSET_FILE = join(OFFSET_DIR, "update-offset");
+let updateOffset = 0;
+async function loadOffset() {
+    try {
+        const data = await readFile(OFFSET_FILE, "utf-8");
+        const parsed = parseInt(data.trim(), 10);
+        if (!isNaN(parsed))
+            updateOffset = parsed;
+    }
+    catch {
+        // File doesn't exist yet — start from 0
+    }
+}
+async function saveOffset() {
+    await mkdir(OFFSET_DIR, { recursive: true });
+    await writeFile(OFFSET_FILE, String(updateOffset), "utf-8");
+}
+async function getUpdates(limit, timeout) {
+    const params = new URLSearchParams({
+        offset: String(updateOffset),
+        limit: String(limit),
+        timeout: String(timeout),
+        allowed_updates: JSON.stringify(["message"]),
+    });
+    const res = await fetch(`${TELEGRAM_API}/getUpdates?${params}`, {
+        method: "GET",
+        signal: AbortSignal.timeout((timeout + 5) * 1000),
+    });
+    return (await res.json());
+}
+function formatUpdate(update) {
+    const msg = update.message;
+    if (!msg)
+        return `[Update ${update.update_id}] (no message)`;
+    const from = msg.from
+        ? `${msg.from.first_name}${msg.from.username ? ` (@${msg.from.username})` : ""}`
+        : "Unknown";
+    const date = new Date(msg.date * 1000).toISOString();
+    let content = msg.text ?? "";
+    if (msg.photo)
+        content = `[Photo]${msg.caption ? ` ${msg.caption}` : ""}`;
+    if (msg.document)
+        content = `[Document: ${msg.document.file_name ?? "unknown"}]${msg.caption ? ` ${msg.caption}` : ""}`;
+    if (msg.video)
+        content = `[Video: ${msg.video.file_name ?? "unknown"}]${msg.caption ? ` ${msg.caption}` : ""}`;
+    if (msg.audio)
+        content = `[Audio: ${msg.audio.file_name ?? "unknown"}]${msg.caption ? ` ${msg.caption}` : ""}`;
+    return `[${date}] ${from} (chat ${msg.chat.id}): ${content}`;
+}
 async function sendMessage(chatId, text, parseMode, disableNotification) {
     const body = { chat_id: chatId, text };
     if (parseMode)
@@ -211,10 +263,52 @@ server.tool("send_audio", "Send an audio file to a Telegram chat", {
     const res = await sendFile("sendAudio", resolvedChatId, filePath, caption, parseMode, disableNotification);
     return telegramResult(res, `Audio sent to chat ${resolvedChatId}.`);
 });
+// -- get_updates ------------------------------------------------------------
+server.tool("get_updates", "Check for new messages sent to the bot. Returns only new messages since the last check.", {
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(100)
+        .optional()
+        .describe("Max number of messages to retrieve (1-100, default 10)"),
+    timeout: z
+        .number()
+        .int()
+        .min(0)
+        .max(30)
+        .optional()
+        .describe("Long-polling timeout in seconds (0-30, default 0). Set >0 to wait for new messages."),
+}, async ({ limit, timeout }) => {
+    const effectiveLimit = limit ?? 10;
+    const effectiveTimeout = timeout ?? 0;
+    let res;
+    try {
+        res = await getUpdates(effectiveLimit, effectiveTimeout);
+    }
+    catch (err) {
+        return errorResult(`Failed to fetch updates: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!res.ok) {
+        return errorResult(`Telegram API error: ${res.description ?? "Unknown error"}`);
+    }
+    const updates = res.result ?? [];
+    // Advance the offset and persist so we survive restarts
+    if (updates.length > 0) {
+        updateOffset = updates[updates.length - 1].update_id + 1;
+        await saveOffset();
+    }
+    if (updates.length === 0) {
+        return successResult("No new messages.");
+    }
+    const formatted = updates.map(formatUpdate).join("\n");
+    return successResult(`${updates.length} new message(s):\n\n${formatted}`);
+});
 // ---------------------------------------------------------------------------
 // Start
 // ---------------------------------------------------------------------------
 async function main() {
+    await loadOffset();
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error("Telegram Notifier MCP server running on stdio");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "telegram-notifier-mcp",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "MCP server for sending notifications via Telegram Bot API",
   "type": "module",
   "bin": {
@@ -18,6 +18,19 @@
     "@modelcontextprotocol/sdk": "^1.12.1",
     "zod": "^3.24.2"
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AdeshAtole/telegram-notifier-mcp.git"
+  },
+  "homepage": "https://github.com/AdeshAtole/telegram-notifier-mcp#readme",
+  "keywords": [
+    "mcp",
+    "telegram",
+    "notifications",
+    "bot",
+    "model-context-protocol"
+  ],
+  "license": "MIT",
   "devDependencies": {
     "typescript": "^5.7.3",
     "@types/node": "^22.13.4"