MCP-сервер Telegram: безопасный доступ AI-агентов ко всему Telegram Bot API

Зачем AI-агентам мост к Telegram

AI-агенты всё лучше справляются с реальными инструментами. Они могут прочитать дашборд, понять, что важно, и сделать следующий шаг. Но чтобы действовать в Telegram, им нужен мост: то, что превращает фразу вроде «закрепи анонс AMA и открой тему для вопросов» в правильные вызовы Telegram API.

Этот мост и есть MCP-сервер Telegram.

Model Context Protocol (MCP) это открытый стандарт, который позволяет AI-клиентам, таким как Claude, ChatGPT, Cursor и Codex, находить инструменты и вызывать их. MCP-сервер Telegram предоставляет действия в Telegram именно в виде таких инструментов, с понятными описаниями и схемами входных данных, которым может следовать модель.

Теперь Metricgram запускает такой сервер за вас и использует бота, который уже управляет вашими группами.

Что на самом деле значит «обернуть» Telegram Bot API

На бумаге подготовить Bot API для агента кажется простой задачей. На практике нужно:

• Хостить бота, хранить его токен в секрете и следить, чтобы он не падал.
• Получать обновления через вебхуки или polling.
• Написать описание инструмента для каждого эндпоинта, который должен использовать агент.
• Не дать агенту публиковать в чатах, которых он никогда не должен касаться.
• Обрабатывать лимиты запросов, мигрировавшие супергруппы и сообщения об ошибках Telegram.
• Сделать повторы безопасными, чтобы один нестабильный сетевой запрос не отправил одно и то же сообщение дважды.
• Логировать действия агента на случай, если позже придётся их объяснять.

Большинство команд останавливаются на «отправить сообщение», потому что всё остальное требует много инфраструктурной работы. В итоге получается агент, который умеет говорить, но не умеет по-настоящему управлять сообществом.

Как работает MCP-сервер Telegram от Metricgram

Metricgram уже работает в ваших Telegram-группах как бот-администратор (или как ваш собственный бот). MCP-сервер просто позволяет вашему AI-клиенту использовать этого бота через облачный эндпоинт:

1. Подключите свои группы к Metricgram и выдайте боту права администратора.
2. Добавьте эндпоинт https://metricgram.com/api/v1/mcp в свой AI-клиент, например как пользовательский коннектор в Claude.
3. Войдите и подтвердите доступ через OAuth. Вот и всё: никаких серверов, вебхуков и токенов. Клиенты без OAuth могут вместо этого использовать API-ключ с конфигурацией ниже.

{
  "mcpServers": {
    "metricgram": {
      "url": "https://metricgram.com/api/v1/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Пользователи Claude Desktop могут подключить тот же эндпоинт через mcp-remote. Готовые фрагменты конфигурации для каждого клиента есть на странице MCP в вашем Manager.

Более 70 методов Bot API и два способа их вызвать

Сервер предоставляет Telegram Bot API на двух уровнях.

Типизированные инструменты для повседневных задач

Для частых задач есть отдельные инструменты с понятными параметрами, которые модели легко использовать правильно:

• send_telegram_message с темами, ответами и URL-кнопками
• send_telegram_media для фото, видео, GIF, документов, аудио и стикеров
• send_telegram_poll для опросов и викторин
• edit_telegram_message, delete_telegram_messages, react_to_telegram_message
• pin_telegram_message и forward_telegram_message
• manage_forum_topic для создания, переименования, закрытия, повторного открытия и удаления тем
• get_telegram_chat и get_telegram_chat_member для актуальных данных чата
• handle_telegram_join_request, create_telegram_invite_link и update_telegram_chat_settings

Полный шлюз Bot API

Всё остальное проходит через telegram_bot_api. Агент передаёт официальное название метода Bot API и его параметры, например setChatPermissions, banChatSenderChat, editMessageMedia, hideGeneralForumTopic или revokeChatInviteLink. Вспомогательный инструмент telegram_api_methods показывает все методы, доступные текущему ключу, поэтому агент всегда знает, что ему разрешено.

Безопасность: почему агент никогда не выбирает chat_id

Самое важное проектное решение касается того, чего агент не может сделать.

• Чат зафиксирован. Агент передаёт group_id из Metricgram. Сервер определяет chat_id в Telegram по группе, которой вы владеете, и отклоняет любой другой чат.
• Пересылки и цитаты проверяются. Переслать, скопировать или процитировать сообщение можно только из ваших собственных групп.
• Действия на уровне всего бота исключены. Вебхуки, платежи, изменения профиля бота и выход из группы недоступны.
• Кнопки безопасны. Inline-кнопки могут открывать ссылки или копировать текст, но не могут отправлять callback-запросы боту.
• Права соответствуют уровню доверия. telegram:read, telegram:write, telegram:moderate и telegram:admin разделены, и вы можете держать несколько ключей с разными возможностями.
• Повторы идемпотентны. Инструменты записи принимают idempotency_key, поэтому повторный вызов возвращает первый результат, а не выполняет действие дважды.
• Каждый вызов логируется вместе с инструментом и использованным методом Bot API.

Агент действует от имени бота через официальный Bot API и никогда от имени вашего личного аккаунта Telegram.

Контекст, которого нет у обычного бота

Простая обёртка над Bot API умеет действовать, но видит немного. MCP-сервер Metricgram также предоставляет данные о сообществе:

• Обзор аналитики и временные ряды активности
• Активных участников, историю участников и сохранённые сообщения
• Рейтинги и награды геймификации
• AI-сводки о том, что происходило в группе
• Состояние подписчиков Stripe и продления под угрозой

Это значит, что агент может ответить на вопрос «кто перестал участвовать в этом месяце?», а затем отправить этим людям продуманное сообщение, и всё это в одном диалоге.

Примеры сценариев

Еженедельный анонс. «Опубликуй в Crypto Talk еженедельный анонс AMA, закрепи его без уведомления всех участников, открой тему для вопросов к AMA и создай ссылку-приглашение, которая истечёт в пятницу».

Модерационная чистка. «Проверь последние 200 сообщений на спам-ссылки, удали их и ограничь отправителей на 24 часа».

Отчёт о сообществе. «Сравни активность этой недели с прошлой, перечисли пять самых активных участников и опубликуй короткое благодарственное сообщение в теме General».

Разбор заявок на вступление. «Одобри ожидающие заявки на вступление от пользователей с активной подпиской, а остальные отклони».

Для кого это

• Владельцы сообществ, которым нужен помощник для рутинной администраторской работы.
• Агентства, которые ведут много клиентских групп и хотят одного агента на все.
• Команды поддержки и customer success, которые ведут клиентские сообщества в Telegram.
• Разработчики, которые хотят добавить Telegram в свой стек агентов без поддержки инфраструктуры бота.

Как начать

MCP-сервер входит в каждый тариф Metricgram и в бесплатный 14-дневный пробный период, поэтому вы можете подключить агента до оплаты. Большинство клиентов подключаются через OAuth: вставьте URL сервера, войдите и подтвердите доступ. Для клиентов без OAuth по-прежнему доступны API-ключи.

Подробнее читайте на странице MCP-сервера Telegram и в обзоре возможностей MCP, а затем создайте свой первый ключ в Manager.