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
/newbotand 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
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
/startto 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