io.github.ParthJadhav/telegram-notify-mcp

Official

by ParthJadhav · TypeScript

Send Telegram notifications from AI agents — text, photos, and documents.

The io.github.ParthJadhav/telegram-notify-mcp server is an MCP server for sending Telegram notifications from AI agents. Its description specifies delivery of text, photos, and documents, and its readme excerpt states the single purpose is to send AI agent progress notifications to users on Telegram.

🛠️ Key Features

Sends Telegram notifications from AI agents
Supports text, photos, and documents
Focused on agent progress updates

🚀 Use Cases

Notifying a user when an AI agent makes progress
Delivering agent outputs that include text, images, or files via Telegram

⚡ Developer Benefits

Minimal, single-job MCP server design for progress notifications
Clear scope aligned to Telegram message content types (text, photos, documents)

⚠️ Limitations

The description indicates one main job (sending progress notifications); no additional chat or administration capabilities are evidenced in the provided excerpt

README.md3 KBView on GitHub

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

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

bash

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:

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

Install

Configuration

Environment variables

TELEGRAM_BOT_TOKENrequiredsecret

Telegram Bot API token from BotFather

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "telegram-notify-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@parthj/telegram-notify-mcp@1.0.1"
      ],
      "env": {
        "TELEGRAM_BOT_TOKEN": "<YOUR_TELEGRAM_BOT_TOKEN>"
      }
    }
  }
}

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Telegram Notify MCP

Quick Start

1. Create a Telegram Bot

2. Start a chat with your bot

3. Add to your MCP client

Claude Code

Claude Desktop / Cursor / Windsurf

Configuration

Tools

send_message

send_photo

send_document

How It Works

Development

License

Install

Configuration

Related servers

`send_message`

`send_photo`

`send_document`