MTM - MCP Telegram MORE

Пользовательский Telegram-канал для Claude Code — это демон + MCP-сервер + MiniApp, который превращает Telegram-бота в полноценный пульт дистанционного управления для ваших сессий Claude.

Возможности

Удаленный чат с Claude

• Отправляйте сообщения Claude из любого Telegram-клиента; ответы Claude транслируются обратно таким же образом.

• Поддерживаются вложения файлов в обоих направлениях (загрузка / скриншоты / скачивание).

• MiniApp внутри бота с тремя вкладками: Чат, Задачи, Статус.

Подтверждение инструментов через Telegram

• Каждое рискованное действие инструмента (Bash, Edit, Write, инструменты MCP и т. д.) может требовать явного подтверждения.

• Запросы на подтверждение приходят в виде сообщений Telegram с кнопками «Разрешить»/«Отклонить»; вы подтверждаете их со своего телефона.

• Список разрешенных инструментов на уровне инструментов позволяет автоматически одобрять безопасные инструменты (/allow Read, /deny Bash sudo).

• Глобальный режим YOLO (/yolo on) временно отключает подтверждения.

Отслеживание задач в реальном времени

• Список TodoWrite Claude зеркалируется на вкладку «Задачи» в реальном времени.

• Переходы состояний (ожидание → в процессе → завершено) обновляются в реальном времени через WebSocket.

Видимость субагентов и инструментов

• Закрепленная строка состояния в верхней части MiniApp показывает, что Claude делает прямо сейчас («main: Edit · config.ts», «main + 2 субагента запущены»).

• Сворачиваемые пузырьки агентов для каждого запущенного субагента — можно просмотреть инструменты, которые использовал каждый субагент.

• Важные инструменты (действия записи, Task, MCP) выделены; инструменты только для чтения по умолчанию свернуты.

• История событий инструментов по умолчанию сохраняется 7 дней (настраивается).

Осведомленность о рабочем пространстве

• Несколько одновременных сессий Claude в разных проектах, каждая из которых привязана к своему рабочему пространству.

• Команда /ws в боте переключает рабочее пространство, на которое направляются входящие сообщения.

Контроль доступа

• Процесс сопряжения: напишите боту в ЛС → получите 6-значный код → активируйте его с помощью /mcp-telegram:access pair <code>.

• Список разрешенных с ролями owner/user; owner может повышать права и удалять пользователей.

• Режимы политики: pairing (только код), allowlist (закрытый), open (любой — только для разработки).

Абстракция туннеля

• Публичный URL предоставляется через подключаемого провайдера туннелей.

• URL по умолчанию автоматически отправляется в Telegram в качестве кнопки MiniApp бота, включая переопределения для каждого чата для всех пользователей из списка разрешенных.

Related MCP server: Straight Connect

Предварительные требования

• Bun — curl -fsSL https://bun.sh/install | bash

• Инструмент туннелирования, соответствующий выбранному вами провайдеру:

  • cloudflared — установить (по умолчанию)

  • tuna — установить (альтернатива)

  • Или используйте свой собственный URL через режим manual

• Токен Telegram-бота от @BotFather (используйте /newbot).

• Node.js (для скриптов хуков Claude Code — любая свежая версия).

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

# 1. Clone & install workspace deps
git clone <repo> mcp-telegram && cd mcp-telegram
bun install

# 2. Put the bot token into the daemon's env file
mkdir -p ~/.mcp-tg
echo "TELEGRAM_BOT_TOKEN=<your-bot-token>" > ~/.mcp-tg/.env

# 3. Build the MiniApp (served statically by the daemon)
bun run --cwd packages/miniapp build

# 4. Start the daemon (long-running; keep in a terminal or use install-service)
bun run --cwd packages/daemon start
# Logs print the public tunnel URL and port 17080.

# 5. Load the plugin into Claude Code (for hook + MCP integration)
claude --dangerously-load-development-channels plugin:mcp-telegram@mcp-telegram-local

# 6. From inside Claude Code, configure and pair
/mcp-telegram:configure <BOT_TOKEN>
# DM your bot in Telegram → receive a 6-digit pair code
/mcp-telegram:access pair ABC123

# 7. Open the MiniApp by tapping the "Open" button in the bot chat.

Конфигурация

~/.mcp-tg/.env (обязательно)

Переменные считываются из ~/.mcp-tg/.env демоном при запуске; вы также можете экспортировать их в своей оболочке.

~/.mcp-tg/config.json (управляется демоном)

Управляется демоном и навыком /mcp-telegram:configure. Ключи:

• tunnel_provider — один из cloudflared | tuna | manual | none.

• tunnel_manual_url — используется только когда tunnel_provider = manual; должен быть публично доступным HTTPS URL, проксирующим на 127.0.0.1:17080.

• default_workspace — необязательный слаг, используемый для широковещательных системных событий до подключения любого рабочего пространства.

Выбор провайдера туннеля

# Default: cloudflared (auto-generated trycloudflare URL, rotates per restart)
/mcp-telegram:configure tunnel cloudflared

# tuna.am alternative
/mcp-telegram:configure tunnel tuna

# Bring-your-own public URL (nginx, frp, your domain, etc.)
/mcp-telegram:configure tunnel manual
# then edit ~/.mcp-tg/config.json and set tunnel_manual_url to your HTTPS endpoint.

# No public access (local MiniApp only; Telegram bot still works for chat)
/mcp-telegram:configure tunnel none

После смены провайдера перезапустите демон. Новый URL автоматически отправляется в Telegram-бота — как в качестве кнопки MiniApp по умолчанию, так и для переопределения в каждом чате для всех пользователей из списка разрешенных.

Команды с косой чертой (в Claude Code)

Все навыки взаимодействуют с запущенным демоном по адресу http://127.0.0.1:17080/admin/* с использованием токена носителя в ~/.mcp-tg/admin.token (автоматически генерируется при первом запуске, режим 0600).

Команды бота (в Telegram)

Внеполосно: отправьте любой текст, не являющийся командой, в ЛС, чтобы отправить его в сессию Claude текущего выбранного рабочего пространства.

Развертывание

Для разового использования достаточно bun run --cwd packages/daemon start в терминале. Для чего-то постоянного:

# Linux — systemd user service (starts at login, restarts on failure)
/mcp-telegram:install-service

# Logs: journalctl --user -u mcp-telegram -f
# Stop: systemctl --user stop mcp-telegram
# Disable: systemctl --user disable mcp-telegram

В macOS / Windows запускайте демон под управлением вашего собственного менеджера процессов (launchd, pm2, nssm и т. д.) — MVP не поставляется со скриптами установки для этих платформ.

Архитектура (кратко)

• daemon (packages/daemon) — единственный долгоживущий процесс. Владеет ботом, HTTP + WS серверами, SQLite, туннелем и состоянием подтверждений.

• mcp-server (packages/mcp-server) — процесс stdio, запускаемый для каждой сессии Claude Code; тонкий WebSocket-клиент демона.

• miniapp (packages/miniapp) — React SPA, собирается один раз, обслуживается статически демоном по URL туннеля.

• shared (packages/shared) — протокол, статус и типы событий инструментов.

• plugin (plugin/) — плагин Claude Code с конфигурацией MCP-сервера, хуками подтверждений, хуком синхронизации TodoWrite и хуком событий инструментов субагента.

Полная документация по дизайну находится в docs/superpowers/specs/.

Тесты

bun test                          # all workspaces
bun test --cwd packages/daemon    # daemon-only
bun test --cwd packages/miniapp   # MiniApp (vitest)

Безопасность

• Коды сопряжения хранятся только в оперативной памяти — перезапуск демона аннулирует их; напишите боту в ЛС для получения нового кода.

• Никогда не подтверждайте запрос на сопряжение, который пришел через самого бота. Навык /mcp-telegram:access отклоняет операции, инициированные из Telegram, чтобы предотвратить инъекции команд через сообщения.

• initData MiniApp проверяется на стороне сервера (HMAC-SHA256 согласно спецификации Telegram). JWT MiniApp живут 15 минут.

• Демон привязывается к 127.0.0.1; публичный доступ возможен только через провайдера туннеля.

• MCP_TG_HOOK_TOKEN — единственная учетная запись, требуемая хуками; она остается внутри ~/.mcp-tg/.env (режим 0600) и никогда не отправляется за пределы 127.0.0.1.

• История событий инструментов очищается после MCP_TG_TOOL_EVENTS_TTL_DAYS (по умолчанию 7); индекс agent_sessions сохраняется бессрочно как компактный аудиторский след.