telegram-bot-mcp

MCP-сервер, который позволяет Claude управлять Telegram-каналом через Telegram Bot API — отслеживать рост подписчиков день за днём, а также публиковать, редактировать, закреплять или удалять посты.

🇮🇷 راهنمای فارسی · Руководство по развертыванию · راهنمای دپلوی

Что это такое

Telegram Bot API — это обычный HTTPS API. Этот репозиторий оборачивает его в Model Context Protocol, чтобы ИИ-ассистент мог вызывать его как инструменты — «как канал показал себя на этой неделе?» вместо curl https://api.telegram.org/bot.../getChatMemberCount.

Он поставляется в двух формах, на основе одних и тех же определений инструментов:

Выбирайте удалённый сервер, если вам нужны ежедневные отчёты, работающие без вашего участия. Выбирайте плагин, если вы используете только Claude Code и предпочитаете, чтобы ничего не покидало вашу машину.

Инструменты

Обе сборки предоставляют одни и те же восемь инструментов.

Быстрый старт (удалённый сервер)

1. Создайте бота с помощью @BotFather → /newbot → скопируйте токен.

2. Добавьте бота как администратора вашего канала.

3. Создайте HTTP-val на val.town и вставьте содержимое remote/telegram-mcp.ts.

4. Установите три переменные окружения на боковой панели val: TELEGRAM_BOT_TOKEN, TELEGRAM_CHANNEL, MCP_PASSWORD.

5. В Claude: Настройки → Коннекторы → Добавить пользовательский коннектор → https://<your-val>.web.val.run/mcp → введите ваш пароль.

Полное руководство, включая путь локального плагина и устранение неполадок: docs/deployment.md.

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

В этом репозитории не хранятся учётные данные. config.json и .env находятся в .gitignore; отслеживаются только файлы .example. Перед отправкой любого форка убедитесь с помощью git status, что ни один из них не появляется.

Удалённый сервер реализует полный поток авторизации OAuth 2.1, а не просто открыт в интернете:

• Запросы без действительного bearer-токена получают 401 с заголовком WWW-Authenticate, указывающим на метаданные ресурса, согласно RFC 9728.

• Клиенты регистрируются динамически (RFC 7591); распространять секреты клиентов не нужно.

• Коды авторизации защищены с помощью PKCE (S256), а URI перенаправления проверяются на соответствие зарегистрированному набору.

• Токены доступа и обновления подписаны HMAC-SHA256 и не имеют состояния — доступ на 24 часа, обновление на 30 дней.

• Экран согласия защищён паролем MCP_PASSWORD, который вы выбираете.

Ваш токен бота остаётся в переменных окружения хоста и никогда не возвращается ни одним инструментом.

Относитесь к MCP_PASSWORD как к паролю от вашего канала. Любой, у кого он есть, может подключиться и публиковать посты.

Ограничения

Bot API сообщает только количество подписчиков. Просмотры постов, репосты, охват и официальные графики статистики канала Telegram недоступны ботам — для этого требуется MTProto-клиент, вошедший в систему с учётной записью пользователя, который администрирует канал.

Бот обычно может редактировать только те сообщения, которые отправил сам. Telegram определяет право администратора can_edit_messages («может редактировать сообщения других пользователей; только для каналов»), но поведение бота в отношении постов, опубликованных администраторами-людьми, чётко не документировано — проверьте это на своём канале, прежде чем полагаться на это. Удаление — другое дело: can_delete_messages явно охватывает сообщения других пользователей.

Для сравнения роста требуется, чтобы хранилище истории сохранялось между запусками. На Val Town это blob-хранилище, и оно сохраняется. В локальном плагине это CSV-файл — храните его в надёжном месте, а не во временной папке.

Структура репозитория

remote/telegram-mcp.ts              Remote MCP server (Val Town HTTP val, Deno)
plugin/                             Claude Code plugin
  .claude-plugin/plugin.json          Plugin manifest
  .mcp.json                           stdio MCP server registration
  server/telegram_mcp_server.py        MCP server (Python 3, stdlib only)
  skills/telegram-channel-report/      Skill that turns tools into a readable report
  config.example.json                  Template — copy to config.json
tests/                              Test suite for the remote server
docs/                               Deployment guides (English / فارسی)

Тесты

npm test

Требуется Node 22.6+. Двадцать две проверки охватывают поток OAuth (вызов 401, документы обнаружения, динамическую регистрацию, отклонение PKCE, выдачу токена и обновление, отклонение поддельного токена) и протокол MCP (инициализация, уведомления, список инструментов, арифметика дельты роста, пути ошибок инструментов). Telegram API имитируется; сетевой доступ и реальный токен бота не нужны.

Набор тестов запускается непосредственно на развёрнутом исходном коде — tests/build.mjs переписывает ровно одну строку, импорт blob-хранилища Val Town, и больше ничего не меняет.

Лицензия

MIT