telegram-notify-mcp 1.0.0

package/.env.example

@@ -0,0 +1,3 @@
+# Copy to your MCP host env — do not commit real values
+TELEGRAM_BOT_TOKEN=
+TELEGRAM_CHAT_ID=

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ehsan Eskandari pour
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,159 @@
+# telegram-notify-mcp
+
+**MCP connector / server** (stdio) that talks to the [Telegram Bot HTTP API](https://core.telegram.org/bots/api) using **your own** bot from [@BotFather](https://t.me/BotFather) (BYOB — bring your own bot).
+
+This package is **not** a Grok Bot agent, chat persona, or hosted SaaS. It is a local Model Context Protocol server you run under Cursor, Grok Bot, or any MCP host. No secrets ship in the repo; configuration is environment-only.
+
+**Publisher:** Ehsan Eskandari pour
+
+## How it works
+
+1. You create a Telegram bot with BotFather and receive an HTTP API token.
+2. You run this MCP server with `TELEGRAM_BOT_TOKEN` (and optionally `TELEGRAM_CHAT_ID`) in the process environment.
+3. Your MCP host (Cursor / Grok Bot / etc.) lists the tools and can call them over stdio.
+4. Tools call `api.telegram.org` to verify the bot, discover chat ids, and send notifications.
+
+Phase 1 is outbound notify only — no inbound webhooks.
+
+## Tools (Phase 1)
+
+| Tool | Purpose |
+|------|---------|
+| `telegram_get_me` | `getMe` — verify token; return bot id/username |
+| `telegram_send_message` | Send text (`chat_id` optional if env default set) |
+| `telegram_notify` | Short completion notification (`title?` + `body`) |
+| `telegram_get_updates` | List recent updates to discover `chat_id` after `/start` |
+
+## BotFather setup
+
+1. Open Telegram and chat with [@BotFather](https://t.me/BotFather).
+2. Send `/newbot`, choose a display name and a username ending in `bot`.
+3. Copy the **HTTP API token** BotFather gives you. This is `TELEGRAM_BOT_TOKEN`.
+4. (Optional) Leave privacy defaults; for personal notify bots this is fine.
+
+**Never commit the token.** Put it only in MCP env / your secret store.
+
+## How to get `chat_id`
+
+1. Start this MCP server with `TELEGRAM_BOT_TOKEN` set (no `TELEGRAM_CHAT_ID` yet).
+2. In Telegram, open your bot and tap **Start** (or send `/start`).
+3. Call tool `telegram_get_updates` (optional `limit`).
+4. Read `discovered_chats[].chat_id` from the result.
+5. Set `TELEGRAM_CHAT_ID` to that value so `telegram_notify` / `telegram_send_message` can omit `chat_id`.
+
+Private chats use a numeric id (e.g. `123456789`). Groups/channels may use negative ids.
+
+## Install
+
+Requires **Node.js 20+**.
+
+```bash
+npm install telegram-notify-mcp
+# or from a release tarball / local path (GitHub repo not published yet):
+cd /absolute/path/to/telegram-notify-mcp
+npm install
+npm run build
+npm test
+```
+
+Environment variables (see [`.env.example`](./.env.example)):
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `TELEGRAM_BOT_TOKEN` | Yes (for tool calls) | BotFather HTTP API token |
+| `TELEGRAM_CHAT_ID` | No | Default chat for send/notify |
+
+The process starts even if `TELEGRAM_BOT_TOKEN` is missing (so the host can list tools); tool calls then return a clear error until the token is set.
+
+## Add MCP in Cursor / Grok Bot
+
+Use a **local** command + env. Example with a built clone:
+
+```json
+{
+  "mcpServers": {
+    "telegram-notify": {
+      "command": "node",
+      "args": [
+        "/absolute/path/to/telegram-notify-mcp/dist/index.js"
+      ],
+      "env": {
+        "TELEGRAM_BOT_TOKEN": "123456:ABC-DEF...",
+        "TELEGRAM_CHAT_ID": "123456789"
+      }
+    }
+  }
+}
+```
+
+Or via `npx` after publishing / linking:
+
+```json
+{
+  "mcpServers": {
+    "telegram-notify": {
+      "command": "npx",
+      "args": [
+        "--yes",
+        "telegram-notify-mcp"
+      ],
+      "env": {
+        "TELEGRAM_BOT_TOKEN": "123456:ABC-DEF...",
+        "TELEGRAM_CHAT_ID": "123456789"
+      }
+    }
+  }
+}
+```
+
+If your host UI has **Add MCP** fields instead of raw JSON:
+
+- **command:** `node`
+- **args:** `/absolute/path/to/telegram-notify-mcp/dist/index.js`
+- **env:** `TELEGRAM_BOT_TOKEN`, optional `TELEGRAM_CHAT_ID`
+
+## Example notify flow
+
+1. Configure token (+ optional default chat id) as above; reload MCP.
+2. `telegram_get_me` → confirm username.
+3. If needed: message the bot, then `telegram_get_updates` → set `TELEGRAM_CHAT_ID`.
+4. When a task finishes, call `telegram_notify` with title/body. Example payload:
+
+```json
+{
+  "title": "Deploy finished",
+  "body": "staging is live; smoke tests passed."
+}
+```
+
+You should receive a Telegram message like:
+
+```text
+✅ Deploy finished
+
+staging is live; smoke tests passed.
+```
+
+See also [`skill-snippet.md`](./skill-snippet.md) for agent-oriented usage notes.
+
+## Security notes
+
+- Token grants full control of the bot — treat it like a password.
+- This server only calls `api.telegram.org`; it does not open inbound webhooks in Phase 1.
+- Configuration is **env-only** for the published server. Do not commit tokens or chat ids.
+- No secrets are stored in this repository.
+
+## Contact
+
+- **Author:** Ehsan Eskandari pour
+- **Email:** e.eskandaripour7@gmail.com
+- **Website:** https://digitalhand.site
+- **Source:** GitHub repo is not published yet — install from the release tarball or a local path (not `git clone` of a public URL).
+
+## License
+
+MIT — see [LICENSE](./LICENSE).
+
+## Roadmap
+
+Phase 2 ideas (inbound / control) are sketched in [ROADMAP.md](./ROADMAP.md).

package/ROADMAP.md

@@ -0,0 +1,21 @@
+# Roadmap
+
+## Phase 1 (this release)
+
+- [x] stdio MCP connector/server
+- [x] `telegram_get_me`, `telegram_send_message`, `telegram_notify`, `telegram_get_updates`
+- [x] BYOB BotFather token via env only
+- [x] Unit tests with mocked fetch
+- [ ] Publish to npm (`telegram-notify-mcp`)
+- [ ] Optional Cursor / MCP marketplace plugin listing
+
+## Phase 2 (later) — inbound / control
+
+Not implemented yet. Possible directions:
+
+- Optional long-poll or webhook receiver so hosts can **read** user replies / commands from Telegram
+- Simple allowlisted control verbs (e.g. `/status`, `/cancel`) mapped to host-side hooks
+- Multi-chat routing and per-chat rate limits
+- Richer notify templates (progress, failure, links) without embedding secrets
+
+Phase 2 must remain local-first (no mandatory hosted SaaS) and keep the BotFather BYOB model.

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * telegram-notify-mcp — stdio MCP server for Telegram Bot API notifications.
+ * Env: TELEGRAM_BOT_TOKEN (required for tool calls), TELEGRAM_CHAT_ID (optional default).
+ * Starts cleanly without a token; tools fail with a clear error when invoked.
+ * Public release is env-only — no disk/secret-store token loading.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+/**
+ * telegram-notify-mcp — stdio MCP server for Telegram Bot API notifications.
+ * Env: TELEGRAM_BOT_TOKEN (required for tool calls), TELEGRAM_CHAT_ID (optional default).
+ * Starts cleanly without a token; tools fail with a clear error when invoked.
+ * Public release is env-only — no disk/secret-store token loading.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { TelegramApiError, TelegramClient, formatNotifyMessage, getDefaultChatId, } from './telegram.js';
+const SERVER_NAME = 'telegram-notify-mcp';
+const SERVER_VERSION = '1.0.0';
+function textResult(text, isError = false) {
+    return {
+        content: [{ type: 'text', text }],
+        isError,
+    };
+}
+function errorResult(err) {
+    if (err instanceof TelegramApiError) {
+        return textResult(err.message, true);
+    }
+    const msg = err instanceof Error ? err.message : String(err);
+    return textResult(msg, true);
+}
+function getClient() {
+    return new TelegramClient(process.env.TELEGRAM_BOT_TOKEN);
+}
+function createServer() {
+    const server = new McpServer({
+        name: SERVER_NAME,
+        version: SERVER_VERSION,
+    });
+    server.tool('telegram_get_me', 'Call Telegram getMe and return the bot id, username, and name. Useful to verify TELEGRAM_BOT_TOKEN.', async () => {
+        try {
+            const me = await getClient().getMe();
+            return textResult(JSON.stringify({
+                id: me.id,
+                username: me.username ?? null,
+                first_name: me.first_name,
+                is_bot: me.is_bot,
+            }, null, 2));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    server.tool('telegram_send_message', 'Send a text message via the Bot API. chat_id is optional when TELEGRAM_CHAT_ID is set.', {
+        text: z.string().min(1).describe('Message text to send'),
+        chat_id: z
+            .union([z.string(), z.number()])
+            .optional()
+            .describe('Telegram chat id (falls back to TELEGRAM_CHAT_ID)'),
+        parse_mode: z
+            .enum(['Markdown', 'MarkdownV2', 'HTML'])
+            .optional()
+            .describe('Optional Telegram parse_mode'),
+    }, async ({ text, chat_id, parse_mode }) => {
+        try {
+            const chatId = getDefaultChatId(chat_id);
+            const msg = await getClient().sendMessage({
+                chat_id: chatId,
+                text,
+                parse_mode,
+            });
+            return textResult(JSON.stringify({
+                ok: true,
+                message_id: msg.message_id,
+                chat_id: msg.chat.id,
+                text: msg.text ?? text,
+            }, null, 2));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    server.tool('telegram_notify', 'Send a short completion-style notification (title + body) to the default or explicit chat.', {
+        body: z.string().min(1).describe('Notification body / details'),
+        title: z.string().optional().describe('Optional short title (e.g. "Build finished")'),
+        chat_id: z
+            .union([z.string(), z.number()])
+            .optional()
+            .describe('Telegram chat id (falls back to TELEGRAM_CHAT_ID)'),
+    }, async ({ body, title, chat_id }) => {
+        try {
+            const chatId = getDefaultChatId(chat_id);
+            const text = formatNotifyMessage(title, body);
+            const msg = await getClient().sendMessage({
+                chat_id: chatId,
+                text,
+            });
+            return textResult(JSON.stringify({
+                ok: true,
+                message_id: msg.message_id,
+                chat_id: msg.chat.id,
+                text,
+            }, null, 2));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    server.tool('telegram_get_updates', 'Fetch recent bot updates so you can discover chat_id after messaging the bot with /start.', {
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .optional()
+            .describe('Max updates to return (default 10)'),
+    }, async ({ limit }) => {
+        try {
+            const updates = await getClient().getUpdates({ limit: limit ?? 10 });
+            const chats = new Map();
+            for (const u of updates) {
+                const m = u.message ?? u.edited_message ?? u.channel_post;
+                if (!m?.chat)
+                    continue;
+                const c = m.chat;
+                const label = c.title ||
+                    [c.first_name, c.last_name].filter(Boolean).join(' ') ||
+                    c.username ||
+                    String(c.id);
+                chats.set(String(c.id), { chat_id: c.id, type: c.type, label });
+            }
+            return textResult(JSON.stringify({
+                update_count: updates.length,
+                discovered_chats: [...chats.values()],
+                updates: updates.map((u) => {
+                    const m = u.message ?? u.edited_message ?? u.channel_post;
+                    return {
+                        update_id: u.update_id,
+                        chat_id: m?.chat?.id ?? null,
+                        from: m?.from?.username ?? m?.from?.first_name ?? null,
+                        text: m?.text ?? null,
+                    };
+                }),
+            }, null, 2));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    return server;
+}
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`${SERVER_NAME} v${SERVER_VERSION} running on stdio` +
+        (process.env.TELEGRAM_BOT_TOKEN ? '' : ' (TELEGRAM_BOT_TOKEN not set — tools will error until configured)'));
+}
+main().catch((err) => {
+    console.error('Fatal:', err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/telegram.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Thin Telegram Bot HTTP API client (api.telegram.org).
+ * Uses Node 20+ global fetch. No secrets are hardcoded.
+ */
+export declare class TelegramApiError extends Error {
+    readonly status?: number | undefined;
+    readonly description?: string | undefined;
+    constructor(message: string, status?: number | undefined, description?: string | undefined);
+}
+export interface TelegramUser {
+    id: number;
+    is_bot: boolean;
+    first_name: string;
+    username?: string;
+    can_join_groups?: boolean;
+    can_read_all_group_messages?: boolean;
+    supports_inline_queries?: boolean;
+}
+export interface TelegramChat {
+    id: number;
+    type: string;
+    title?: string;
+    username?: string;
+    first_name?: string;
+    last_name?: string;
+}
+export interface TelegramMessage {
+    message_id: number;
+    date: number;
+    chat: TelegramChat;
+    text?: string;
+    from?: TelegramUser;
+}
+export interface TelegramUpdate {
+    update_id: number;
+    message?: TelegramMessage;
+    edited_message?: TelegramMessage;
+    channel_post?: TelegramMessage;
+}
+export interface TelegramApiResponse<T> {
+    ok: boolean;
+    result?: T;
+    description?: string;
+    error_code?: number;
+}
+export type ParseMode = 'Markdown' | 'MarkdownV2' | 'HTML';
+export interface SendMessageParams {
+    chat_id: string | number;
+    text: string;
+    parse_mode?: ParseMode;
+    disable_notification?: boolean;
+}
+export interface GetUpdatesParams {
+    limit?: number;
+    timeout?: number;
+    offset?: number;
+}
+export declare function getDefaultChatId(explicit?: string | number): string | number;
+export declare function formatNotifyMessage(title: string | undefined, body: string): string;
+export declare class TelegramClient {
+    private readonly fetchImpl;
+    private readonly baseUrl;
+    constructor(token?: string | undefined, fetchImpl?: typeof fetch);
+    private call;
+    getMe(): Promise<TelegramUser>;
+    sendMessage(params: SendMessageParams): Promise<TelegramMessage>;
+    getUpdates(params?: GetUpdatesParams): Promise<TelegramUpdate[]>;
+}
+export declare function createClientFromEnv(fetchImpl?: typeof fetch): TelegramClient;

package/dist/telegram.js

@@ -0,0 +1,103 @@
+/**
+ * Thin Telegram Bot HTTP API client (api.telegram.org).
+ * Uses Node 20+ global fetch. No secrets are hardcoded.
+ */
+export class TelegramApiError extends Error {
+    status;
+    description;
+    constructor(message, status, description) {
+        super(message);
+        this.status = status;
+        this.description = description;
+        this.name = 'TelegramApiError';
+    }
+}
+function requireToken(token) {
+    const t = (token ?? '').trim();
+    if (!t) {
+        throw new TelegramApiError('TELEGRAM_BOT_TOKEN is not set. Create a bot with @BotFather, copy the token, and set TELEGRAM_BOT_TOKEN in the MCP server env.');
+    }
+    return t;
+}
+export function getDefaultChatId(explicit) {
+    if (explicit !== undefined && explicit !== null && String(explicit).trim() !== '') {
+        return explicit;
+    }
+    const fromEnv = (process.env.TELEGRAM_CHAT_ID ?? '').trim();
+    if (!fromEnv) {
+        throw new TelegramApiError('No chat_id provided and TELEGRAM_CHAT_ID is not set. Message your bot (/start), then call telegram_get_updates to discover your chat id.');
+    }
+    return fromEnv;
+}
+export function formatNotifyMessage(title, body) {
+    const t = (title ?? '').trim();
+    const b = body.trim();
+    if (t) {
+        return `✅ ${t}\n\n${b}`;
+    }
+    return `✅ ${b}`;
+}
+export class TelegramClient {
+    fetchImpl;
+    baseUrl;
+    constructor(token = process.env.TELEGRAM_BOT_TOKEN, fetchImpl = globalThis.fetch.bind(globalThis)) {
+        this.fetchImpl = fetchImpl;
+        const t = requireToken(token);
+        this.baseUrl = `https://api.telegram.org/bot${t}`;
+    }
+    async call(method, body) {
+        const url = `${this.baseUrl}/${method}`;
+        let res;
+        try {
+            res = await this.fetchImpl(url, {
+                method: body ? 'POST' : 'GET',
+                headers: body ? { 'Content-Type': 'application/json' } : undefined,
+                body: body ? JSON.stringify(body) : undefined,
+            });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new TelegramApiError(`Network error calling Telegram ${method}: ${msg}`);
+        }
+        let data;
+        try {
+            data = (await res.json());
+        }
+        catch {
+            throw new TelegramApiError(`Telegram ${method} returned non-JSON (HTTP ${res.status})`, res.status);
+        }
+        if (!res.ok || !data.ok) {
+            throw new TelegramApiError(`Telegram ${method} failed: ${data.description ?? res.statusText ?? 'unknown error'}`, data.error_code ?? res.status, data.description);
+        }
+        return data.result;
+    }
+    getMe() {
+        return this.call('getMe');
+    }
+    sendMessage(params) {
+        const payload = {
+            chat_id: params.chat_id,
+            text: params.text,
+        };
+        if (params.parse_mode)
+            payload.parse_mode = params.parse_mode;
+        if (params.disable_notification !== undefined) {
+            payload.disable_notification = params.disable_notification;
+        }
+        return this.call('sendMessage', payload);
+    }
+    getUpdates(params = {}) {
+        const payload = {};
+        if (params.limit !== undefined)
+            payload.limit = params.limit;
+        if (params.timeout !== undefined)
+            payload.timeout = params.timeout;
+        if (params.offset !== undefined)
+            payload.offset = params.offset;
+        return this.call('getUpdates', Object.keys(payload).length ? payload : undefined);
+    }
+}
+export function createClientFromEnv(fetchImpl) {
+    return new TelegramClient(process.env.TELEGRAM_BOT_TOKEN, fetchImpl);
+}
+//# sourceMappingURL=telegram.js.map

package/dist/telegram.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telegram.js","sourceRoot":"","sources":["../src/telegram.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "telegram-notify-mcp",
+  "version": "1.0.0",
+  "description": "MCP connector/server that sends Telegram notifications via your own BotFather bot (BYOB).",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "telegram-notify-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "test": "node --import tsx --test tests/telegram.test.ts",
+    "prepare": "tsc"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "ROADMAP.md",
+    "skill-snippet.md",
+    ".env.example"
+  ],
+  "keywords": [
+    "mcp",
+    "telegram",
+    "notifications",
+    "botfather",
+    "model-context-protocol"
+  ],
+  "author": {
+    "name": "Ehsan Eskandari pour",
+    "email": "e.eskandaripour7@gmail.com",
+    "url": "https://digitalhand.site"
+  },
+  "homepage": "https://digitalhand.site",
+  "bugs": {
+    "url": "https://digitalhand.site/contact",
+    "email": "e.eskandaripour7@gmail.com"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.18.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  }
+}

package/skill-snippet.md

@@ -0,0 +1,34 @@
+# Skill snippet — Telegram notify
+
+Use when the user wants a Telegram ping after work completes, or to verify the bot.
+
+This package is an **MCP connector/server**, not a chat agent. Configure it in your MCP host (Cursor, Grok Bot, or similar), then call its tools.
+
+## Preconditions
+
+- MCP server `telegram-notify` (or `telegram-notify-mcp`) is configured with `TELEGRAM_BOT_TOKEN`.
+- Prefer `TELEGRAM_CHAT_ID` in env; otherwise pass `chat_id` on each call.
+
+## Discover chat id (once)
+
+1. Ask the user to open the bot in Telegram and send `/start`.
+2. Call `telegram_get_updates`.
+3. Read `discovered_chats[].chat_id` and suggest setting `TELEGRAM_CHAT_ID`.
+
+## Notify on completion
+
+Call `telegram_notify` with:
+
+- `title`: short status (e.g. `Tests passed`, `PR ready`)
+- `body`: one or two lines of detail (paths, URLs, next step)
+- `chat_id`: only if no default env chat
+
+Keep messages short. Do not put tokens or passwords in the body.
+
+## Verify bot
+
+Call `telegram_get_me` if sends fail or after rotating the token.
+
+## Raw send
+
+Use `telegram_send_message` when you need a custom `parse_mode` or non-notify wording.