# telegram-notify-mcp

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.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 7
- Author: ParthJadhav
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/ParthJadhav/telegram-notify-mcp
- Updated: 2026-03-13
- HTML: https://affpapa.org/en/nevibecode/mcp/telegram-notify-mcp

## What it 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.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `TELEGRAM_BOT_TOKEN` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add telegram-notify-mcp -e TELEGRAM_BOT_TOKEN=<TELEGRAM_BOT_TOKEN> -- npx -y @parthj/telegram-notify-mcp
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add telegram-notify-mcp --env TELEGRAM_BOT_TOKEN=<TELEGRAM_BOT_TOKEN> -- npx -y @parthj/telegram-notify-mcp
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "telegram-notify-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@parthj/telegram-notify-mcp"
            ],
            "env": {
                "TELEGRAM_BOT_TOKEN": "<TELEGRAM_BOT_TOKEN>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "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

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e TELEGRAM_BOT_TOKEN=<TELEGRAM_BOT_TOKEN> telegram-notify-mcp npx -y @parthj/telegram-notify-mcp
```
Replace <…> with your own values

## When to use it
- 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
- 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.pdf` document to my Telegram chat.

## Similar
- [claude-ops-telegram-server](https://affpapa.org/en/nevibecode/mcp/claude-ops-telegram-server.md) — MCP server · ★ 547
- [Notify MCP Server](https://affpapa.org/en/nevibecode/mcp/notify-mcp-server.md) — MCP server · ★ 29
- [TONNode — TON blockchain access](https://affpapa.org/en/nevibecode/mcp/tonnode-ton-blockchain-access.md) — MCP server · ★ 27
- [telegram-mcp](https://affpapa.org/en/nevibecode/mcp/telegram-mcp.md) — MCP server · ★ 7

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md