Claude Telegram Alerts

An MCP server that sends Telegram alerts for Claude Code status updates. Get notified on your phone when:

• Claude needs your input or approval
• Long-running tasks complete
• Builds finish or tests pass/fail
• Any custom status update you configure

Features

• alert - Send status alerts to your Telegram (normal or urgent priority)
• get_chat_id - Helper tool to retrieve your Telegram chat ID during setup

Quick Start

1. Create a Telegram Bot

1. Open Telegram and message @BotFather
2. Send /newbot and follow the prompts
3. Copy your bot token (e.g., 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)

2. Message Your Bot

Search for your new bot in Telegram and send it any message (e.g., "hi"). This enables the bot to message you back.

3. Install

git clone https://github.com/anthony-potts/claude-telegram-alerts.git
cd claude-telegram-alerts
npm install
npm run build

4. Configure Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "telegram-alerts": {
      "command": "node",
      "args": ["/path/to/claude-telegram-alerts/build/index.js"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your-bot-token",
        "TELEGRAM_CHAT_ID": ""
      }
    }
  }
}

5. Get Your Chat ID

Restart Claude Code, then ask:

"Use the get_chat_id tool to find my Telegram chat ID"

Update your config with the returned chat ID, then restart Claude Code.

Usage Examples

Manual Alerts

"Send me a Telegram alert that the deployment is complete"

"Send an urgent alert that I need to approve the PR"

Automated Workflows

"Run the test suite and alert me on Telegram when done"

"Deploy to staging and send me a Telegram alert with the result"

"When you need my input, send me a Telegram alert"

Status Updates

"Alert me via Telegram: Build failed - missing dependency in package.json"

"Send Telegram alert: Waiting for approval to delete 50 files"

Tools

alert

Send a status alert to your Telegram.

Parameter	Type	Required	Description
message	string	Yes	The alert message
priority	"normal" | "urgent"	No	urgent = notification sound. Default: normal (silent)

get_chat_id

Retrieve your chat ID after messaging the bot. No parameters.

Troubleshooting

Error	Solution
"TELEGRAM_BOT_TOKEN required"	Add your bot token to the MCP server env config
"TELEGRAM_CHAT_ID required"	Run get_chat_id tool and add the result to config
"No messages found"	Send a message to your bot in Telegram first
Alerts not arriving	Check Telegram notifications aren't muted for the bot

Development

npm install      # Install dependencies
npm run build    # Compile TypeScript
npm run dev      # Watch mode

License

MIT