telegram-notify-mcp — Claude Code MCP server: setup guide
Delivers status updates and generated files to your Telegram chat from an AI coding agent. Useful when running long builds while away from the desk.
claude mcp add telegram-notify-mcp -e TELEGRAM_BOT_TOKEN=<TELEGRAM_BOT_TOKEN> -- npx -y @parthj/telegram-notify-mcpWhat telegram-notify-mcp does
The server provides three tools: send_message, send_photo, and send_document. It handles formatted text along with files passed by absolute path or remote URL. Group moderation is completely excluded.
Everything runs through the Telegram Bot API. On the initial call, the server resolves your handle to a chat ID using getUpdates and caches that ID. If you do not send /start to your bot first, message delivery will fail. Telegram forbids bots from contacting users out of nowhere.
Configuration requires a bot token from @BotFather and your username set in TELEGRAM_USERNAME. No extra databases are involved.
What it helps with
- receive push alerts when an agent finishes running lengthy tasks
- forward terminal logs and build artifacts directly to Telegram
- inspect UI screenshots on mobile without opening the local folder
Example prompts for the agent
- Run the test suite and send me a Telegram message when it passes.
- Take a screenshot of the landing page and send the photo to my Telegram.
- Send the
dist/report.pdfdocument to my Telegram chat.
How to install telegram-notify-mcp
Platform CLI
claude mcp add telegram-notify-mcp -e TELEGRAM_BOT_TOKEN=<TELEGRAM_BOT_TOKEN> -- npx -y @parthj/telegram-notify-mcpReplace <…> with your own values
Platform CLI
codex mcp add telegram-notify-mcp --env TELEGRAM_BOT_TOKEN=<TELEGRAM_BOT_TOKEN> -- npx -y @parthj/telegram-notify-mcpReplace <…> with your own values
Config file
{
"mcpServers": {
"telegram-notify-mcp": {
"command": "npx",
"args": [
"-y",
"@parthj/telegram-notify-mcp"
],
"env": {
"TELEGRAM_BOT_TOKEN": "<TELEGRAM_BOT_TOKEN>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"telegram-notify-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@parthj/telegram-notify-mcp"
],
"env": {
"TELEGRAM_BOT_TOKEN": "<TELEGRAM_BOT_TOKEN>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e TELEGRAM_BOT_TOKEN=<TELEGRAM_BOT_TOKEN> telegram-notify-mcp npx -y @parthj/telegram-notify-mcpReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about telegram-notify-mcp
How to install telegram-notify-mcp in Claude Code?
Run claude mcp add telegram-notify-mcp -e TELEGRAM_BOT_TOKEN=<TELEGRAM_BOT_TOKEN> -- npx -y @parthj/telegram-notify-mcp. Replace <TELEGRAM_BOT_TOKEN> with your token from @BotFather.
What does telegram-notify-mcp do?
It exposes tools for dispatching text updates, pictures, and documents straight into your personal Telegram messages. You can step away while autonomous coding sessions finish their work.
Why does the bot fail to send notifications?
The bot cannot initiate chats on its own. You must open Telegram and send /start to your bot so it can discover your chat ID via getUpdates.
