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.