English Français العربية

io.github.ParthJadhav/telegram-notify-mcp

Official registry Productivity

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

Source code Documentation

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

NPM package @parthj/telegram-notify-mcp
Claude Code 
claude mcp add telegram-notify-mcp -e 'TELEGRAM_BOT_TOKEN=<your telegram_bot_token>' -- npx -y @parthj/telegram-notify-mcp@1.0.1
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "telegram-notify-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@parthj/telegram-notify-mcp@1.0.1"
            ],
            "env": {
                "TELEGRAM_BOT_TOKEN": "<your telegram_bot_token>"
            }
        }
    }
}

Environment variables

  • TELEGRAM_BOT_TOKEN required secret Telegram Bot API token from BotFather

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. Telegram Notify MCP
  2. Quick Start
  3. Configuration
  4. Tools
  5. How It Works
  6. Development
  7. License

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

Frequently asked questions

What is io.github.ParthJadhav/telegram-notify-mcp?

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

How do I install io.github.ParthJadhav/telegram-notify-mcp?

It runs on your machine. In Claude Code: claude mcp add telegram-notify-mcp -e 'TELEGRAM_BOT_TOKEN=<your telegram_bot_token>' -- npx -y @parthj/telegram-notify-mcp@1.0.1. For other clients, paste the JSON configuration from this page into their MCP settings.

Does io.github.ParthJadhav/telegram-notify-mcp need an API key?

Yes. It expects TELEGRAM_BOT_TOKEN, which you set in its configuration.

Is io.github.ParthJadhav/telegram-notify-mcp open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains io.github.ParthJadhav/telegram-notify-mcp?

It is published by ParthJadhav. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.