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

Related MCP server: mcp-telegram-claudecode

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.

get_chat_id

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

Troubleshooting

Development

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

License

MIT