claude-telegram-interactive-mcp

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 / 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

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 and get your TELEGRAM_BOT_TOKEN.

2. Get your numeric Telegram ID via @userinfobot for TELEGRAM_CHAT_ID.

3. Configure in Claude Code (~/.claude.json or settings.json)

Add the server to your mcpServers block:

{
  "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)

{
  "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:

# 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.

Related MCP server: Telegram Notify MCP Server

Русский

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 и 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. Клонирование и зависимости

git clone https://github.com/makarworld/claude-telegram-interactive-mcp.git
cd claude-telegram-interactive-mcp
npm install

2. Создание бота

1. Создайте бота в @BotFather и скопируйте токен.

2. Узнайте свой chat_id через @userinfobot.

3. Подключение к Claude Code (~/.claude.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