Telegram Notify Mcp

io.github.ParthJadhavPublished by GitHub account ParthJadhavv1.0.1Updated Oct 24, 2026

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

VerifiedSTDIODesktop onlyCommunication & Collaboration

Overview

AI-generated overview

Lets an assistant send Telegram notifications to you as text messages, photos, or documents.

What you can do
A small MCP server with three tools: send_message for text updates, send_photo for images such as screenshots or charts, and send_document for files like reports, logs, or build artifacts. It resolves your Telegram username to a chat ID on the first call and caches it for the process lifetime. It does no chat or group management.
When to use it
Useful when you start a long-running agent task and want progress or completion notices pushed to Telegram instead of watching the terminal. Also handy for delivering generated images or files to your phone.
Requirements
Runs locally over stdio, typically via npx, so Node.js is needed. Requires a Telegram bot token from BotFather in TELEGRAM_BOT_TOKEN and your Telegram username in TELEGRAM_USERNAME. You must send /start to the bot first so it can find your chat ID. Network access to the Telegram Bot API is required.
Before you install
The bot token in TELEGRAM_BOT_TOKEN is a credential that grants control of the bot; keep it out of shared configs. Messages, photos, and documents are sent to Telegram's servers, so anything the assistant forwards leaves your machine. The server only sends; it does not read or manage chats.

Installation

In SourceWeft

  1. Open Telegram Notify Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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

bash
git clone https://github.com/ParthJadhav/telegram-notify-mcp.gitcd telegram-notify-mcpnpm installnpm run build

License

MIT

Source: README.md at commit 9eecb61

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v1.0.1LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts