Telegram MCP Server

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

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

Инструменты

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

Related MCP server: telegram-mcp

Требования

• 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)

Запуск

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.