Telegram Notify MCP

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

Message @BotFather on Telegram
Send /newbot and follow the prompts
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

Terminal

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:

config.json

{
  "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

bash

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

License

MIT