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 Variable	Required	Description
TELEGRAM_BOT_TOKEN	Yes	Bot token from @BotFather
TELEGRAM_USERNAME	Yes	Your Telegram username (without the @)

Tools

Three tools. That's the entire surface area.

send_message

Send a text update to the user.

Parameter	Type	Required	Description
text	string	Yes	The message text
parse_mode	string	No	HTML, Markdown, or MarkdownV2

send_photo

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

Parameter	Type	Required	Description
photo	string	Yes	URL or absolute file path
caption	string	No	Photo caption
parse_mode	string	No	Caption formatting mode

send_document

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

Parameter	Type	Required	Description
document	string	Yes	URL or absolute file path
caption	string	No	Document caption
parse_mode	string	No	Caption 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