Telegram MCP Server

MCP-сервер для Telegram-канала. Предоставляет read-only доступ к постам, комментариям, реакциям и агрегированной статистике через MCP-протокол (Streamable HTTP). Работает по MTProto (GramJS), поэтому видит всю историю канала, а не только новые сообщения.

Сервер физически не умеет писать: используются только read-методы MTProto (messages.GetHistory, messages.GetReplies, messages.Search, channels.GetFullChannel, messages.GetMessageReactionsList).

Инструменты

Инструмент	Описание
get_channel_info	Метаданные канала: название, username, id, дата создания, описание, подписчики, закреплённый пост, доступные реакции, связанная группа обсуждений
list_posts	Последние посты: дата, текст в Markdown, просмотры, форварды, число комментариев, реакции, медиа, ссылка t.me
get_post	Один или несколько постов по id с полным текстом, медиа-метаданными и результатами опроса
get_post_comments	Ветка комментариев поста из связанной группы, с reply_to_message_id для вложенности
search_channel	Поиск по тексту (индекс Telegram) в постах или в комментариях
get_reactions	Разбивка реакций по эмодзи; опционально — кто именно поставил
get_channel_stats	Агрегаты: средние/медианные просмотры, реакции по эмодзи, комментарии, форварды, engagement rate, активность по дням/часам, топ-посты
get_top_commenters	Самые активные участники обсуждений: число комментариев, средняя длина, полученные реакции, период активности

Аргумент channel во всех тулах опционален — если не передан, используется TG_CHANNEL из .env.

Требования

• Node.js 18+
• api_id / api_hash с https://my.telegram.org → API development tools
• Telegram-аккаунт, который видит канал (для публичного канала подписка не обязательна)

Установка

npm install
cp .env.example .env
# указать TG_API_ID, TG_API_HASH, API_KEY, TG_CHANNEL
npm run login          # одноразовая авторизация → выведет TG_SESSION
# скопировать TG_SESSION=... в .env

Конфигурация (.env)

Переменная	Назначение
PORT	Порт MCP-сервера (default 3200)
API_KEY	Ключ доступа — клиенты передают в X-API-Key или Authorization: Bearer <key>
TG_API_ID	api_id с my.telegram.org
TG_API_HASH	api_hash с my.telegram.org
TG_SESSION	Строка сессии из npm run login
TG_CHANNEL	Канал по умолчанию: @username, ссылка t.me/... или -100<id>
TG_FLOOD_SLEEP_THRESHOLD	Сек: автоматически пересиживать FLOOD_WAIT короче этого значения (default 60)

Запуск

npm start        # прод
npm run dev      # с автоперезапуском (--watch)

• MCP endpoint: POST http://<host>:<PORT>/mcp (требует API-ключ)
• Health check: GET http://<host>:<PORT>/health — проверяет соединение с Telegram и показывает аккаунт

Подключение MCP-клиента

{
  "mcpServers": {
    "telegram": {
      "url": "http://<host>:<PORT>/mcp",
      "headers": { "Authorization": "Bearer <API_KEY>" }
    }
  }
}

Замечания

• TG_SESSION = полный доступ к аккаунту. Держите его в секрете, не коммитьте, используйте отдельный аккаунт под аналитику.
• Комментарии существуют только если у канала подключена группа обсуждений. Без неё get_post_comments и get_top_commenters вернут понятную ошибку.
• Числовые id (-100...) резолвятся только если чат уже известен сессии; надёжнее указывать @username.
• Флуд-лимиты: тяжёлые тулы (get_channel_stats, get_top_commenters) листают историю страницами. Не выставляйте лимиты в максимум без необходимости; FLOOD_WAIT короче TG_FLOOD_SLEEP_THRESHOLD пересиживается автоматически.
• Форматирование постов конвертируется из Telegram entities в Markdown: **bold**, _italic_, `code`, ```pre```, [text](url), ||spoiler||, ~~strike~~, цитаты — как markdown-blockquote.