Telegram Notify

A compact MCP server that sends agent progress updates to Telegram as text, images, or files.

javascript

5

GitHub Stars

javascript

Language

3 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "parthjadhav-telegram-notify-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@parthj/telegram-notify-mcp"
      ],
      "env": {
        "TELEGRAM_USERNAME": "your-telegram-username",
        "TELEGRAM_BOT_TOKEN": "your-bot-token"
      }
    }
  }
}

This MCP server sends AI agent progress updates to you on Telegram, providing simple notifications as text, images, or files. It’s tiny, focused, and works in the background to keep you informed while your agent runs.

How to use

You can use this MCP server by adding it to your MCP client configuration. Once set up, you start your agent and you will receive Telegram notifications when progress is made or when tasks complete.

How to install

Prerequisites: ensure you have Node.js and npm installed on your machine.

Create a Telegram bot and get its token. Follow these steps to create the bot: start a chat with BotFather, send /newbot, and copy the bot token.
Start a chat with your bot so it can discover your chat ID. Open Telegram, find your bot, and send /start.
Add the MCP server to your client configuration using one of the supported methods shown below.

claude mcp add telegram -e TELEGRAM_BOT_TOKEN=your-token -e TELEGRAM_USERNAME=your-username -- npx @parthj/telegram-notify-mcp

Additional configuration and examples

Configuration details are provided through environment variables and the MCP client settings. The following examples show how to run and configure the Telegram notify MCP server.

{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": ["-y", "@parthj/telegram-notify-mcp"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your-bot-token",
        "TELEGRAM_USERNAME": "your-telegram-username"
      }
    }
  }
}

How it works

On the first tool call, the server uses the Telegram Bot API to resolve your username to a chat ID. Telegram requires you to have started a conversation with the bot by sending /start. The chat ID is cached for the duration of the process, and subsequent notifications are delivered to that chat.

Security and notes

Keep your bot token secure. Do not share your token or expose it in public files. Only you should configure the bot token and Telegram username used by the MCP server.

Available tools

send_message

Send a text update to the user. Parameters: text (string, required), parse_mode (string, optional: HTML, Markdown, or MarkdownV2).

send_photo

Send an image. Parameters: photo (string, required: URL or absolute file path), caption (string, optional), parse_mode (string, optional).

send_document

Send a file. Parameters: document (string, required: URL or absolute file path), caption (string, optional), parse_mode (string, optional).