# Claude Code Telegram Notifier MCP Server 🤖📲

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue?logo=typescript)](https://www.typescriptlang.org/)
[![Model Context Protocol](https://img.shields.io/badge/MCP-Compatible-green)](https://modelcontextprotocol.io/)

A **Model Context Protocol (MCP)** server that connects **Claude Code** and **Claude Desktop** to **Telegram**. Receive real-time push notifications on your phone or desktop whenever Claude starts long tasks, hits key milestones, encounters blockers, or finishes work — perfect for when you are away from your keyboard (AFK).

---

## ✨ Features

- 🔔 **Proactive Notifications**: Claude notifies you automatically about task status without manual intervention.
- 🚦 **Status Types**:
  - `info` ℹ️: Task started, background work initiated.
  - `success` ✅: Milestone reached, task completed.
  - `warning` ⚠️: Non-critical issue, retry, or blocker.
  - `action_required` 🚨: Human intervention needed (approval, missing API key, confirmation).
- 🛡️ **Resilient Delivery**: Automatic fallback to plain text if Markdown entity parsing fails due to unescaped code or paths.
- ⚙️ **Dual Configuration**: Supports both `.env` file and MCP configuration `env` block.
- 🔌 **Universal Compatibility**: Works with Claude Code CLI and Claude Desktop app.

---

## 📋 Prerequisites

1. **Node.js** (v18 or higher) & **npm**
2. **Telegram Bot Token**:
   - Open Telegram and message [@BotFather](https://t.me/BotFather).
   - Send `/newbot` and follow the instructions to create your bot.
   - Copy the API token provided.
3. **Telegram User ID**:
   - Message [@userinfobot](https://t.me/userinfobot) or [@rawdatabot](https://t.me/rawdatabot) to get your numeric Telegram User ID.

---

## 🚀 Installation & Setup

### 1. Clone & Build

```bash
git clone git@github.com:hsynj/ClaudeCode-Telegram-MCPTool.git
cd ClaudeCode-Telegram-MCPTool
npm install
npm run build
```

### 2. Configure Environment

Copy the example environment file and fill in your credentials:

```bash
cp .env.example .env
```

Edit `.env`:

```env
BOT_TOKEN=123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ
ADMIN_ID=987654321
```

*Note: You can also specify these variables directly in your Claude configuration files.*

---

## 🛠️ Configuration with Claude

### Option A: Claude Code CLI

Add the server to Claude Code using `claude mcp add`:

```bash
claude mcp add telegram-notifier node /ABSOLUTE_PATH_TO/ClaudeCode-Telegram-MCPTool/dist/index.js -e BOT_TOKEN=YOUR_BOT_TOKEN -e ADMIN_ID=YOUR_ADMIN_ID
```

Or manually configure your MCP settings file (e.g. `~/.claude/mcp.json` or project-level `.claude/settings.json`):

```json
{
  "mcpServers": {
    "telegram-notifier": {
      "command": "node",
      "args": [
        "/ABSOLUTE_PATH_TO/ClaudeCode-Telegram-MCPTool/dist/index.js"
      ],
      "env": {
        "BOT_TOKEN": "YOUR_BOT_TOKEN",
        "ADMIN_ID": "YOUR_ADMIN_ID"
      }
    }
  }
}
```

### Option B: Claude Desktop App

Edit `claude_desktop_config.json`:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "telegram-notifier": {
      "command": "node",
      "args": [
        "/ABSOLUTE_PATH_TO/ClaudeCode-Telegram-MCPTool/dist/index.js"
      ],
      "env": {
        "BOT_TOKEN": "YOUR_BOT_TOKEN",
        "ADMIN_ID": "YOUR_ADMIN_ID"
      }
    }
  }
}
```

---

## 🧠 Automating Proactive Notifications in Claude Code

To make Claude proactively notify you while working, add a rule to `~/.claude/rules/telegram-notifier.md`:

```markdown
# Telegram Notifier Rule

You MUST proactively use the `send_telegram_update` MCP tool to notify the user in the following situations, without the user explicitly asking:

1. **When starting a multi-step or long-running task:** Let the user know you have started working. Use `status: "info"`.
2. **When reaching significant milestones:** If you've completed a major part of a larger task (e.g. "Finished setting up the database, now moving to API routes"). Use `status: "success"`.
3. **When you encounter a blocker or need human intervention:** If a test fails repeatedly, an API key is missing, or you are stuck and need advice. Use `status: "warning"` or `action_required`.
4. **When you need approval:** If you are about to run a destructive command, modify a critical file, or do something that requires explicit permission. Use `status: "action_required"`.
5. **When the task is completely finished:** Let the user know the work is done and they can review it. Use `status: "success"`.

Assume the user is AFK and relies on Telegram notifications to track progress.
```

---

## 🔧 MCP Tool Specification

### `send_telegram_update`

Sends a formatted notification to your Telegram chat.

| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `project` | `string` | **Yes** | Name of the project or repository being worked on. |
| `message` | `string` | **Yes** | Detailed status log, explanation, or required action. |
| `status` | `string` | **Yes** | One of `info`, `success`, `warning`, `action_required`. |
| `title` | `string` | No | Short headline (defaults to `"Update"`). |

#### Message Format Example:

```text
✅ Milestone Completed
📂 Project: my-web-app

Database migrations applied and all 24 unit tests passed.

Status: success
```

---

## 👨‍💻 Development

```bash
# Run in development mode with ts-node
npm run dev

# Compile TypeScript
npm run build

# Start compiled server
npm start
```

---

## 📄 License

This project is licensed under the [MIT License](LICENSE).