telegram-notifier-mcp 1.0.0

package/README.md

@@ -0,0 +1,192 @@
+# 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.
+
+## Prerequisites
+
+- Node.js 18+
+- A Telegram bot token (from [@BotFather](https://t.me/BotFather))
+- Your Telegram chat ID
+
+## Setup
+
+### 1. Create a Telegram Bot
+
+1. Open Telegram and message [@BotFather](https://t.me/BotFather)
+2. Send `/newbot` and follow the prompts to name your bot
+3. Copy the **bot token** you receive (e.g., `123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11`)
+
+### 2. Find Your Chat ID
+
+1. Send any message to your new bot on Telegram
+2. Open the following URL in your browser, replacing `YOUR_BOT_TOKEN` with your actual token:
+   ```
+   https://api.telegram.org/botYOUR_BOT_TOKEN/getUpdates
+   ```
+3. In the JSON response, find `"chat":{"id": 123456789}` — that number is your chat ID
+
+> **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.
+
+## Adding to Your MCP Client
+
+### Claude Desktop
+
+Add this to your Claude Desktop config file:
+
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "telegram-notifier": {
+      "command": "node",
+      "args": ["/absolute/path/to/telegram-notifier-mcp/build/index.js"],
+      "env": {
+        "TELEGRAM_BOT_TOKEN": "your-bot-token-here",
+        "TELEGRAM_CHAT_ID": "your-chat-id-here"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+Add to your project's `.mcp.json` or global `~/.claude/claude_code_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "telegram-notifier": {
+      "command": "node",
+      "args": ["/absolute/path/to/telegram-notifier-mcp/build/index.js"],
+      "env": {
+        "TELEGRAM_BOT_TOKEN": "your-bot-token-here",
+        "TELEGRAM_CHAT_ID": "your-chat-id-here"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+### `send_message`
+
+Send a text message to a Telegram chat.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `text` | string | Yes | The message text to send |
+| `chatId` | string | No | Target chat ID (overrides `TELEGRAM_CHAT_ID`) |
+| `parseMode` | string | No | `Markdown`, `MarkdownV2`, or `HTML` |
+| `disableNotification` | boolean | No | Send silently without notification sound |
+
+### `send_document`
+
+Send a file/document to a Telegram chat.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `filePath` | string | Yes | Absolute path to the file |
+| `chatId` | string | No | Target chat ID (overrides `TELEGRAM_CHAT_ID`) |
+| `caption` | string | No | Caption for the document |
+| `parseMode` | string | No | `Markdown`, `MarkdownV2`, or `HTML` |
+| `disableNotification` | boolean | No | Send silently without notification sound |
+
+### `send_photo`
+
+Send a photo/image to a Telegram chat.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `filePath` | string | Yes | Absolute path to the image file |
+| `chatId` | string | No | Target chat ID (overrides `TELEGRAM_CHAT_ID`) |
+| `caption` | string | No | Caption for the photo |
+| `parseMode` | string | No | `Markdown`, `MarkdownV2`, or `HTML` |
+| `disableNotification` | boolean | No | Send silently without notification sound |
+
+### `send_video`
+
+Send a video to a Telegram chat.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `filePath` | string | Yes | Absolute path to the video file |
+| `chatId` | string | No | Target chat ID (overrides `TELEGRAM_CHAT_ID`) |
+| `caption` | string | No | Caption for the video |
+| `parseMode` | string | No | `Markdown`, `MarkdownV2`, or `HTML` |
+| `disableNotification` | boolean | No | Send silently without notification sound |
+
+### `send_audio`
+
+Send an audio file to a Telegram chat.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `filePath` | string | Yes | Absolute path to the audio file |
+| `chatId` | string | No | Target chat ID (overrides `TELEGRAM_CHAT_ID`) |
+| `caption` | string | No | Caption for the audio |
+| `parseMode` | string | No | `Markdown`, `MarkdownV2`, or `HTML` |
+| `disableNotification` | boolean | No | Send silently without notification sound |
+
+## 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
+```
+
+This opens a browser UI where you can invoke each tool and see the results.
+
+## Error Handling
+
+The server handles errors gracefully and returns descriptive messages:
+
+| Scenario | Behavior |
+|---|---|
+| Missing `TELEGRAM_BOT_TOKEN` | Server exits at startup with instructions |
+| Missing chat ID (no env var, no parameter) | Returns `isError: true` with message |
+| File not found | Returns `isError: true` with the file path |
+| File exceeds 50 MB | Returns `isError: true` with file size |
+| Telegram API error | Returns `isError: true` with Telegram's error description |
+
+All server logs go to **stderr** so they never interfere with the stdio MCP transport on stdout.
+
+## File Size Limits
+
+Telegram enforces a **50 MB** limit for file uploads via the Bot API. The server validates file size before uploading and returns an error if the limit is exceeded.
+
+## Development
+
+```bash
+# Watch mode — rebuilds on file changes
+npm run dev
+```
+
+## License
+
+MIT

package/build/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/build/index.js

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+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";
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+const TELEGRAM_BOT_TOKEN = process.env.TELEGRAM_BOT_TOKEN;
+const DEFAULT_CHAT_ID = process.env.TELEGRAM_CHAT_ID;
+if (!TELEGRAM_BOT_TOKEN) {
+    console.error("Error: TELEGRAM_BOT_TOKEN environment variable is required.\n" +
+        "Get a token from @BotFather on Telegram.");
+    process.exit(1);
+}
+const TELEGRAM_API = `https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}`;
+const MAX_FILE_SIZE = 50 * 1024 * 1024; // 50 MB
+async function sendMessage(chatId, text, parseMode, disableNotification) {
+    const body = { chat_id: chatId, text };
+    if (parseMode)
+        body.parse_mode = parseMode;
+    if (disableNotification)
+        body.disable_notification = true;
+    const res = await fetch(`${TELEGRAM_API}/sendMessage`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    });
+    return (await res.json());
+}
+const FILE_FIELD = {
+    sendDocument: "document",
+    sendPhoto: "photo",
+    sendVideo: "video",
+    sendAudio: "audio",
+};
+async function sendFile(method, chatId, filePath, caption, parseMode, disableNotification) {
+    // Validate file exists and is within size limit
+    let fileStats;
+    try {
+        fileStats = await stat(filePath);
+    }
+    catch {
+        return { ok: false, description: `File not found: ${filePath}` };
+    }
+    if (fileStats.size > MAX_FILE_SIZE) {
+        return {
+            ok: false,
+            description: `File exceeds 50 MB limit (${(fileStats.size / 1024 / 1024).toFixed(1)} MB): ${filePath}`,
+        };
+    }
+    const fileBuffer = await readFile(filePath);
+    const blob = new Blob([fileBuffer]);
+    const fileName = basename(filePath);
+    const form = new FormData();
+    form.append("chat_id", chatId);
+    form.append(FILE_FIELD[method], blob, fileName);
+    if (caption)
+        form.append("caption", caption);
+    if (parseMode)
+        form.append("parse_mode", parseMode);
+    if (disableNotification)
+        form.append("disable_notification", "true");
+    const res = await fetch(`${TELEGRAM_API}/${method}`, {
+        method: "POST",
+        body: form,
+    });
+    return (await res.json());
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function resolveChatId(overrideChatId) {
+    return overrideChatId || DEFAULT_CHAT_ID || null;
+}
+function successResult(text) {
+    return { content: [{ type: "text", text }] };
+}
+function errorResult(text) {
+    return { content: [{ type: "text", text }], isError: true };
+}
+function telegramResult(res, successMsg) {
+    if (res.ok)
+        return successResult(successMsg);
+    return errorResult(`Telegram API error: ${res.description ?? "Unknown error"}`);
+}
+// ---------------------------------------------------------------------------
+// MCP Server
+// ---------------------------------------------------------------------------
+const server = new McpServer({
+    name: "telegram-notifier",
+    version: "1.0.0",
+});
+// -- send_message -----------------------------------------------------------
+server.tool("send_message", "Send a text message to a Telegram chat", {
+    text: z.string().describe("The message text to send"),
+    chatId: z
+        .string()
+        .optional()
+        .describe("Target chat ID (overrides TELEGRAM_CHAT_ID env var)"),
+    parseMode: z
+        .enum(["Markdown", "MarkdownV2", "HTML"])
+        .optional()
+        .describe("Message formatting mode"),
+    disableNotification: z
+        .boolean()
+        .optional()
+        .describe("Send silently without notification sound"),
+}, async ({ text, chatId, parseMode, disableNotification }) => {
+    const resolvedChatId = resolveChatId(chatId);
+    if (!resolvedChatId) {
+        return errorResult("No chat ID provided. Set TELEGRAM_CHAT_ID env var or pass chatId parameter.");
+    }
+    const res = await sendMessage(resolvedChatId, text, parseMode, disableNotification);
+    return telegramResult(res, `Message sent to chat ${resolvedChatId}.`);
+});
+// -- send_document ----------------------------------------------------------
+server.tool("send_document", "Send a file/document to a Telegram chat", {
+    filePath: z.string().describe("Absolute path to the file to send"),
+    chatId: z
+        .string()
+        .optional()
+        .describe("Target chat ID (overrides TELEGRAM_CHAT_ID env var)"),
+    caption: z.string().optional().describe("Caption for the document"),
+    parseMode: z
+        .enum(["Markdown", "MarkdownV2", "HTML"])
+        .optional()
+        .describe("Caption formatting mode"),
+    disableNotification: z
+        .boolean()
+        .optional()
+        .describe("Send silently without notification sound"),
+}, async ({ filePath, chatId, caption, parseMode, disableNotification }) => {
+    const resolvedChatId = resolveChatId(chatId);
+    if (!resolvedChatId) {
+        return errorResult("No chat ID provided. Set TELEGRAM_CHAT_ID env var or pass chatId parameter.");
+    }
+    const res = await sendFile("sendDocument", resolvedChatId, filePath, caption, parseMode, disableNotification);
+    return telegramResult(res, `Document sent to chat ${resolvedChatId}.`);
+});
+// -- send_photo -------------------------------------------------------------
+server.tool("send_photo", "Send a photo/image to a Telegram chat", {
+    filePath: z.string().describe("Absolute path to the image file to send"),
+    chatId: z
+        .string()
+        .optional()
+        .describe("Target chat ID (overrides TELEGRAM_CHAT_ID env var)"),
+    caption: z.string().optional().describe("Caption for the photo"),
+    parseMode: z
+        .enum(["Markdown", "MarkdownV2", "HTML"])
+        .optional()
+        .describe("Caption formatting mode"),
+    disableNotification: z
+        .boolean()
+        .optional()
+        .describe("Send silently without notification sound"),
+}, async ({ filePath, chatId, caption, parseMode, disableNotification }) => {
+    const resolvedChatId = resolveChatId(chatId);
+    if (!resolvedChatId) {
+        return errorResult("No chat ID provided. Set TELEGRAM_CHAT_ID env var or pass chatId parameter.");
+    }
+    const res = await sendFile("sendPhoto", resolvedChatId, filePath, caption, parseMode, disableNotification);
+    return telegramResult(res, `Photo sent to chat ${resolvedChatId}.`);
+});
+// -- send_video -------------------------------------------------------------
+server.tool("send_video", "Send a video to a Telegram chat", {
+    filePath: z.string().describe("Absolute path to the video file to send"),
+    chatId: z
+        .string()
+        .optional()
+        .describe("Target chat ID (overrides TELEGRAM_CHAT_ID env var)"),
+    caption: z.string().optional().describe("Caption for the video"),
+    parseMode: z
+        .enum(["Markdown", "MarkdownV2", "HTML"])
+        .optional()
+        .describe("Caption formatting mode"),
+    disableNotification: z
+        .boolean()
+        .optional()
+        .describe("Send silently without notification sound"),
+}, async ({ filePath, chatId, caption, parseMode, disableNotification }) => {
+    const resolvedChatId = resolveChatId(chatId);
+    if (!resolvedChatId) {
+        return errorResult("No chat ID provided. Set TELEGRAM_CHAT_ID env var or pass chatId parameter.");
+    }
+    const res = await sendFile("sendVideo", resolvedChatId, filePath, caption, parseMode, disableNotification);
+    return telegramResult(res, `Video sent to chat ${resolvedChatId}.`);
+});
+// -- send_audio -------------------------------------------------------------
+server.tool("send_audio", "Send an audio file to a Telegram chat", {
+    filePath: z.string().describe("Absolute path to the audio file to send"),
+    chatId: z
+        .string()
+        .optional()
+        .describe("Target chat ID (overrides TELEGRAM_CHAT_ID env var)"),
+    caption: z.string().optional().describe("Caption for the audio"),
+    parseMode: z
+        .enum(["Markdown", "MarkdownV2", "HTML"])
+        .optional()
+        .describe("Caption formatting mode"),
+    disableNotification: z
+        .boolean()
+        .optional()
+        .describe("Send silently without notification sound"),
+}, async ({ filePath, chatId, caption, parseMode, disableNotification }) => {
+    const resolvedChatId = resolveChatId(chatId);
+    if (!resolvedChatId) {
+        return errorResult("No chat ID provided. Set TELEGRAM_CHAT_ID env var or pass chatId parameter.");
+    }
+    const res = await sendFile("sendAudio", resolvedChatId, filePath, caption, parseMode, disableNotification);
+    return telegramResult(res, `Audio sent to chat ${resolvedChatId}.`);
+});
+// ---------------------------------------------------------------------------
+// Start
+// ---------------------------------------------------------------------------
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Telegram Notifier MCP server running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "telegram-notifier-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for sending notifications via Telegram Bot API",
+  "type": "module",
+  "bin": {
+    "telegram-notifier-mcp": "build/index.js"
+  },
+  "files": [
+    "build"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.3",
+    "@types/node": "^22.13.4"
+  }
+}