# claude-telegram-interactive-mcp

[English](#english) | [Русский](#русский)

---

## English

**claude-telegram-interactive-mcp** is an interactive Model Context Protocol (MCP) server designed for **Claude Code**, **Cursor**, and other AI coding assistants.

It enables bidirectional communication between your AI assistant and Telegram:
1. **Interactive confirmations with inline buttons or free text (`ask_telegram_confirmation`)**: The assistant asks questions or requests confirmation (diffs, destructive actions, architectural choices) via Telegram inline buttons, free text reply, or attached media instead of terminal prompts.
2. **Error Screenshots & Media Group Ingestion (`fetch_telegram_updates`)**: Send error screenshots, logs, documents, and photos directly to the bot. Claude fetches, automatically downloads them to local disk, verifies their context relevance, and fixes the issue.
3. **On-demand Long Polling**: No background daemon, public IP, webhooks, or open ports required. The polling loop runs only while waiting for user interaction and stops immediately once answered.
4. **Multi-session / Multi-chat parallel support**: Multiple questions and chats are multiplexed concurrently without conflicts.
5. **Skills included (`/tg-lite`, `/tg-full`)**: Ready for [skills.sh](https://skills.sh) / Claude Code skills standard.

---

### Features & Tools

- ❓ **`ask_telegram_confirmation`**: Send questions with inline buttons and wait for button click, text reply, or attached files/photos. All incoming media is automatically downloaded to disk.
- 📥 **`fetch_telegram_updates`**: On-demand fetch of recent Telegram updates. Automatically downloads sent photos, error screenshots, files, and mediagroups to disk so Claude can inspect them.
- 💬 **`send_markdown_message_as_telegram_bot`**: Send HTML/Markdown reports and status updates.
- 📎 **`send_telegram_document`**: Send logs, diffs, and large files directly.
- 🖼️ **`send_telegram_photo`** & 🎥 **`send_telegram_video`**: Send screenshots, diagrams, and video demos.
- ⚡ **Proxy Support**: Native HTTP/HTTPS proxy support (`HTTP_PROXY`, `HTTPS_PROXY`).

---

### Installation & Setup

#### 1. Clone repository & Install dependencies
```bash
git clone https://github.com/makarworld/claude-telegram-interactive-mcp.git
cd claude-telegram-interactive-mcp
npm install
```

#### 2. Get Telegram Bot Token & Chat ID
1. Create a bot using [@BotFather](https://t.me/BotFather) and get your `TELEGRAM_BOT_TOKEN`.
2. Get your numeric Telegram ID via [@userinfobot](https://t.me/userinfobot) for `TELEGRAM_CHAT_ID`.

#### 3. Configure in Claude Code (`~/.claude.json` or `settings.json`)
Add the server to your `mcpServers` block:

```json
{
  "mcpServers": {
    "telegram-notifier": {
      "command": "node",
      "args": ["/absolute/path/to/claude-telegram-interactive-mcp/index.mjs"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "123456789:ABCdefGhIJKlmNoPQRstuVWXyz",
        "TELEGRAM_CHAT_ID": "123456789",
        "HTTP_PROXY": "",
        "HTTPS_PROXY": ""
      }
    }
  }
}
```

#### 4. Configure in Cursor (`.cursor/mcp.json`)
```json
{
  "mcpServers": {
    "telegram-notifier": {
      "command": "node",
      "args": ["C:/path/to/claude-telegram-interactive-mcp/index.mjs"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "123456789:ABCdefGhIJKlmNoPQRstuVWXyz",
        "TELEGRAM_CHAT_ID": "123456789"
      }
    }
  }
}
```

#### 5. Install Skills (skills.sh / Claude Code)
Copy skills into your Claude skills directory:
```bash
# Windows
cp -r skills/* C:/Users/<User>/.claude/skills/

# Linux / macOS
cp -r skills/* ~/.claude/skills/
```

- Run `/tg-lite`: Enables constant progress and plan streaming to Telegram.
- Run `/tg-full`: Directs all user confirmations and questions exclusively to Telegram inline buttons or text/media responses.

---

## Русский

**claude-telegram-interactive-mcp** — интерактивный MCP-сервер для **Claude Code**, **Cursor** и других ИИ-ассистентов.

Превращает Telegram в интерактивный пульт управления агентом с поддержкой приёма скриншотов и медиа:
1. **Интерактивные вопросы и подтверждения (`ask_telegram_confirmation`)**: Бот присылает inline-кнопки прямо в чат Telegram для одобрения диффов, выбора архитектуры или подтверждения действий. Поддерживает ответ текстом или прикреплением файлов/фото.
2. **Приём скриншотов ошибок и медиагрупп (`fetch_telegram_updates`)**: Отправляйте в чат боту пачку скриншотов ошибок или файлов. Claude запрашивает обновления через тул, скачивает все фото на диск, лично валидирует их на соответствие задаче и решает проблему.
3. **On-demand Long Polling (без постоянного демона)**: Цикл поллинга запускается только в момент ожидания ответа и завершается сразу после ответа. Не требует белого IP, портов или вебхуков.
4. **Параллельные вопросы из разных чатов**: Менеджер ожидания на основе `questionId` поддерживает одновременные запросы без конфликтов `offset`.
5. **Скиллы в комплекте (`/tg-lite`, `/tg-full`)**: Полная совместимость со стандартом [skills.sh](https://skills.sh) и Claude Code.

---

### Доступные инструменты (Tools)

- ❓ **`ask_telegram_confirmation`**: Отправка вопроса с кнопками и ожидание ответа (клик, текст или файлы/фото). Автоматически скачивает медиа на диск.
- 📥 **`fetch_telegram_updates`**: Получение последних входящих сообщений и медиагрупп из чата с автоматической загрузкой картинок и документов на диск.
- 💬 **`send_markdown_message_as_telegram_bot`**: Отправка форматированных отчётов (HTML / Markdown).
- 📎 **`send_telegram_document`**: Отправка файлов, логов, патчей (с локального диска или по URL).
- 🖼️ **`send_telegram_photo`** & 🎥 **`send_telegram_video`**: Отправка медиафайлов и скриншотов.

---

### Быстрый старт

#### 1. Клонирование и зависимости
```bash
git clone https://github.com/makarworld/claude-telegram-interactive-mcp.git
cd claude-telegram-interactive-mcp
npm install
```

#### 2. Создание бота
1. Создайте бота в [@BotFather](https://t.me/BotFather) и скопируйте токен.
2. Узнайте свой `chat_id` через [@userinfobot](https://t.me/userinfobot).

#### 3. Подключение к Claude Code (`~/.claude.json`)
```json
{
  "mcpServers": {
    "telegram-notifier": {
      "command": "node",
      "args": ["C:/Projects/claude-telegram-interactive-mcp/index.mjs"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "твой_токен",
        "TELEGRAM_CHAT_ID": "твой_chat_id",
        "HTTPS_PROXY": "http://user:pass@ip:port"
      }
    }
  }
}
```

#### 4. Подключение скиллов
Скопируйте папку `skills/tg-lite` и `skills/tg-full` в `~/.claude/skills/`.

- `/tg-lite` — отправка отчетов по каждому плану, шагу и завершению.
- `/tg-full` — полный интерактивный режим с опросом через inline-кнопки и поддержкой скриншотов/медиа.

---

### Лицензия
MIT License © 2026 [makarworld](https://github.com/makarworld)