Skip to main content
Glama
claude-telegram-alerts

claude-telegram-alerts

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.

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

Available Tools

2 tools
alertA

Send a Telegram alert for Claude Code status updates. Use this to notify the user when you need input, when tasks complete, or for any important status update.

Inputs: message (required), priority.

get_chat_idA

Get your Telegram chat ID for initial setup. First message your bot in Telegram, then use this tool to retrieve the chat ID.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 2 tools

    Disambiguation5/5

    The two tools have clearly distinct purposes: alert sends notifications, while get_chat_id handles setup. There is no overlap or ambiguity between them.

    Naming Consistency4/5

    Both names use lowercase snake_case and are verb-led, but alert is a bare verb while get_chat_id follows a get_noun pattern. The inconsistency is minor and does not hinder understanding.

    Tool Count3/5

    Two tools is on the thin side for a general-purpose alerting server, but the narrow scope makes the count defensible. It sits at the borderline where the set feels minimal rather than complete.

    Completeness5/5

    The tool surface covers the full intended workflow: retrieve the chat ID during setup, then send alerts. For a notification-only integration, there are no obvious missing operations.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers