mcpField
T
telegram-notify-mcp

telegram-notify-mcp

Local
github.com/ParthJadhavCommunication7Updated 33w ago
Repository

About telegram-notify-mcp

telegram-notify-mcp is a focused MCP server for sending AI agent updates to Telegram. It sends text, images, and files without offering chat or group management.

Key features

  1. 01Send text messages
  2. 02Send photos from URLs or files
  3. 03Send documents from URLs or files

Use cases

  1. 01Receive agent completion notices
  2. 02Get progress updates while an agent runs
  3. 03Send screenshots, reports, or logs to Telegram

MCP support

The MCP server exposes three tools for sending Telegram text messages, photos, and documents.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "parthjadhav-telegram-notify": {
      "command": "npx",
      "args": [
        "-y",
        "@parthj/telegram-notify-mcp"
      ],
      "env": {
        "TELEGRAM_BOT_TOKEN": "<TELEGRAM_BOT_TOKEN>"
      }
    }
  }
}
Run commandnpx -y @parthj/telegram-notify-mcp
Environment variables to set
TELEGRAM_BOT_TOKENSecretTelegram Bot API token from BotFather

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
npm@parthj/telegram-notify-mcp1.0.1

Tools

No tool list yet

Local servers expose tools only once running on your machine, and the maintainer has not provided a tool list.

Details

From the project README

bloom-banner-01-light-tags-1500x500

Telegram Notify MCP

npm version License: MIT

A dead-simple MCP server with one job: send AI agent progress back to you on Telegram.

That's it. No chat management, no group administration, no inline queries. Just notifications — as text, images, or files.

You kick off an agent, walk away, and get a Telegram message when it's done (or while it's working). Nothing more, nothing less.

Quick Start

1. Create a Telegram Bot
  1. Message @BotFather on Telegram
  2. Send /newbot and follow the prompts
  3. Copy the bot token
2. Start a chat with your bot

Find your bot on Telegram and send /start. This is required so the bot can discover your chat ID.

3. Add to your MCP client
Claude Code
claude mcp add telegram -e TELEGRAM_BOT_TOKEN=your-token -e TELEGRAM_USERNAME=your-username -- npx @parthj/telegram-notify-mcp
Claude Desktop / Cursor / Windsurf

Add to your MCP config file:

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

Configuration

Environment VariableRequiredDescription
TELEGRAM_BOT_TOKENYesBot token from @BotFather
TELEGRAM_USERNAMEYesYour Telegram username (without the @)

Tools

Three tools. That's the entire surface area.

send_message

Send a text update to the user.

ParameterTypeRequiredDescription
textstringYesThe message text
parse_modestringNoHTML, Markdown, or MarkdownV2
send_photo

Send an image — a screenshot, a chart, a generated visual.

ParameterTypeRequiredDescription
photostringYesURL or absolute file path
captionstringNoPhoto caption
parse_modestringNoCaption formatting mode
send_document

Send a file — a report, a log, a build artifact.

ParameterTypeRequiredDescription
documentstringYesURL or absolute file path
captionstringNoDocument caption
parse_modestringNoCaption formatting mode

How It Works

  • On the first tool call, the server resolves your username to a chat ID via the Telegram Bot API's getUpdates
  • Sending /start to the bot is required — Telegram bots can only message users who have initiated a conversation
  • The chat ID is cached for the lifetime of the process

Development

git clone https://github.com/ParthJadhav/telegram-notify-mcp.git
cd telegram-notify-mcp
npm install
npm run build

License

MIT

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.