Telegram MCP — следующее поколение

Production-ориентированная интеграция Telegram для MCP-совместимых клиентов, поддерживаемая LoneVertex и построенная на Telethon и Model Context Protocol. Репозиторий сохраняет функциональную поверхность апстрима Telegram, добавляя явные уровни инструментов, контроли изменений с режимом fail-closed, ограничения параллелизма по ключам, ограниченные повторные попытки, локальное кэширование SQLite/FTS5, безопасные пути для медиа, точки входа в пакет и воспроизводимый CI.

Поведение по умолчанию: локальный stdio, уровень инструментов core, без записи в Telegram, без деструктивных операций и без непроверенных корневых каталогов файловой системы.

Управление проектом: Участие · Политика безопасности · Apache License 2.0

Что входит

Реализация регистрирует 128 инструментов: 125 инструментов апстрима, охватывающих аккаунты, чаты, контакты, сообщения, группы, медиа, профили, папки и входящие события, а также cache_health, search_cached_messages и sync_chat_cache. Происхождение апстрима сохранено в коммите 52cca204d945e4ec292801a9d972334c0c2a4b63; версия пакета следующего поколения — 4.0.1.

Установите TELEGRAM_MCP_TIER, чтобы выбрать уровень. Выбранный уровень определяет, какие инструменты регистрируются. TELEGRAM_SEND_ENABLED независимо управляет тем, могут ли выполняться операции записи, а TELEGRAM_DESTRUCTIVE_ENABLED является вторым предохранителем для деструктивных/административных действий. Если предохранитель блокирует вызов, сервер возвращает структурированный ответ nothing_sent или nothing_done.

Related MCP server: telegram-mcp

Быстрый старт

Используйте Python 3.11 или 3.12. Получите учётные данные Telegram API на my.telegram.org/apps и создавайте авторизованную сессию вне процесса MCP с помощью входящего в комплект генератора сессий.

git clone https://github.com/LoneVertex/telegram-mcp-nextgen.git
cd telegram-mcp-nextgen
python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# edit .env with TELEGRAM_API_ID, TELEGRAM_API_HASH, and an authorized session
telegram-mcp

Для разработки пакета и проверки релиза:

pip install -e '.[dev]'
pytest -q
ruff check telegram_mcp/config.py telegram_mcp/core telegram_mcp/db telegram_mcp/models
mypy --explicit-package-bases telegram_mcp/config.py telegram_mcp/core telegram_mcp/db telegram_mcp/models
python -m build

Сервер намеренно неинтерактивен. Используйте telegram-mcp-generate-session перед запуском и держите полученную строку сессии в секрете. Никогда не коммитьте .env, файл .session Telethon, API-хеши и строки сессии.

Конфигурация

Полный шаблон без секретов находится в .env.example. Основные параметры приведены в таблице.

Построение конфигурации не вызывает побочных эффектов. Учётные данные и авторизация проверяются при запуске живого клиента, а не при импорте пакета локальными инструментарием. Состояние во время выполнения создаётся в каталогах, доступных только владельцу, когда это требуется для кэша или сессии.

MCP-клиенты и транспорты

См. config/mcp-configs.md — примеры без секретов для десктопных MCP-клиентов. Локальный stdio предпочтителен. Streamable HTTP доступен для долгоживущего локального сервиса:

MCP_TRANSPORT=http
MCP_HOST=127.0.0.1
MCP_PORT=8765

Не открывайте неаутентифицированный HTTP-эндпоинт напрямую в публичный интернет. При использовании обратного прокси настройте аутентификацию, TLS, разрешённые хосты, разрешённые источники и сетевые контроли. Сервер сохраняет защиту от MCP DNS-rebinding, когда сконфигурирован MCP_ALLOWED_HOSTS.

Параллельность и надёжность

Каждый аккаунт защищён асинхронным мьютексом с ключом и токен-бакетом. Вызовы для одного аккаунта сериализуются на границе адаптера, но для разных меток аккаунтов сохраняется возможность параллельного чтения. Для FloodWait и временных сбоев соединения применяется единая ограниченная политика повторных попыток с экспоненциальной задержкой и джиттером. Консультативные блокировки уровня сессии сохраняются, чтобы два процесса не могли одновременно использовать один и тот же авторизованный ключ Telegram.

Локальный кэш использует SQLite в режиме WAL, внешние ключи, коротко живущие соединения, явные транзакции, индексы для доступа по чату/дате/отправителю/теме и FTS5 для поиска. Синхронизация сохраняет контрольные точки и используют upsert, поэтому изменения отражаются, а не дублируются. Работа с SQLite, создание каталогов и проверки целостности выполняются в рабочих потоках, а не блокируют основной цикл событий.

Безопасность медиа и файловой системы

Файловые инструменты требуют клиентские корни MCP или явные корени на стороне сервера. Пустые или непроверяемые корни приводят к полному запрету, если только намеренно не включён TELEGRAM_ALLOW_SERVER_ROOTS_FALLBACK=true. Пути разрешаются внутри настроенных корней; запрещены обход пути, NUL-байты и выход через символические ссылки. Лимиты размера медиа соблюдаются, а создаваемые файлы получают права доступа только для владельца. Новые примитивы безопасности поддерживают сектора чтения и атомарную замену выходного файла.

Тексты, подписи, имена, подписи кнопок, метаданные медиа и поля входящих событий Telegram являются непроверенным содержимым пользователя. Санитизация и пометки об аудитории сохранены из апстрима; модели не должны рассматривать эти поля как инструкции.

Docker

Образ использует двухэтапную сборку Python 3.12, работает от имени UID 10001, хранит состояние в /var/lib/telegram-mcp и получает учётные данные только во время запуска.

cp .env.example .env
# edit .env
podman compose up --build
# or: docker compose up --build

Compose привязывает HTTP к 127.0.0.1:8765, использует выделяемый именованный том, сбрасывает Linux-возможности, включает no-new-privileges, монтирует корневую файловую систему в режиме только для чтения и предоставляет ограниченный /tmp. Сборка контейнера не выполнялась в песочнице, использувавействой для этой поставки, поскольку Docker был недоступен; CI-процесс проверяет её на runner с поддержкой Docker.

Разработка и этапы версий

Объединённый workflow в .github/workflows/ci.yml запускается на Python 3.11 и 3.12, выполняет унаследованный регрессионный сравнительный план апстрима и тесты следующего поколения, строгие проверки Ruff для новых слоёв продакшена, проверяет mypy с явной базой пакета, компилирует пакет, собирает wheel/sdist, проводит аудит заявленных зависимостей, проверяет Docker-образ и конфигурацию Compose. Переданные в наследство живые адаптеры Telegram остаются покрытыми идущейся отלי hash-регрессионной тестовой набором; локальные модули надежности и безопасности имеют отдельные тесты и покрытие.

Ownership, совместимость и источники

Поддержка проекта: LoneVertex.

Корневой main.py, имена модулей инструментов апстрима, генератор сессий, метки аккаунтов, настройки прокси, переменные MCP-транспорта, устаревший фильтр видимости и лицензия Apache-2.0 апстрима сохранены для совместимости. Новая точка входа пакета — telegram_mcp.runner:main; поддерживается также python -m telegram_mcp. Исходники апстрибека и атрибуция остаются видимыми в истории Git и AUDIT_REPORT.md.

Устранение неполадок

Если при запуске сообщается, что сессия не настроена, создайте авторизованную сессию и задайте TELEGRAM_SESSION_STRING или допустимое имя файла-сессии. Если операция записи возвращает MutationDisabled, задайте TELEGRAM_SEND_ENABLED=true и перезапустие; для удаления или административных операций также задайте TELEGRAM_DESTRUCTIVE_ENABLED=true. Если файловый инструмент сообщает, что корневые каталоги недоступны, настройте MCP Roots клиента или передайте разрешённый корень на стороне сервера в качестве позиционного аргумента. Если FloodWait превышает заданный максимум, вызов намеренно возвращается, а не отключается бесконечно в ожидании. Используйте cache_health для проверки целостности локальной базы SQLite/FTS5 без обращения к Telegram.

Ссылки

Лицензия

Apache License 2.0. См. LICENSE.