telegram-bot

Что умеет

Статус: MVP. Реализован и протестирован локальный MCP-сервер. Для работы настройте собственного бота и подключение клиента. История личного аккаунта, вложения и автоматический планировщик не входят в текущую версию.

Related MCP server: Telegram MCP — Next Generation

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

Нужны Python 3.11+, uv и бот, созданный через @BotFather. Запуск рассчитан на macOS/Linux.

git clone https://github.com/Evr1kys/telegram-bot.git
cd telegram-bot
uv sync --locked
uv run --locked python scripts/configure.py

Мастер настройки попросит токен скрытым вводом и числовые ID чатов. Токен хранится вне репозитория в файле с правами 600. Можно вместо файла внедрить TELEGRAM_BOT_TOKEN через менеджер секретов. Не вставляйте токен в разговор с моделью.

Затем подключите сервер:

Пошаговые инструкции, переменные окружения и разбор ошибок — в руководстве по настройке. Само клонирование не подключает Telegram к ChatGPT.

Три инструмента

• «Покажи новые сообщения из разрешённых Telegram-чатов».

• «Проверь название и тип чата с ID −1001234567890».

• «Отправь в канал −1001234567890: Встреча сегодня в 18:00».

Пример аргументов отправки после поручения пользователя:

{
  "chat_id": -1001234567890,
  "text": "Встреча сегодня в 18:00",
  "request_id": "meeting_20260916_001"
}

Параметр message_thread_id позволяет указать тему форума. Сохраняйте тот же request_id при повторном вызове одного запроса. Новый ID — новая попытка отправки.

Контроль доступа и отправки

Доступ закрыт по умолчанию. Чтение и отправка разрешаются отдельно для конкретных числовых ID. Плагин использует отдельного бота и не входит в личный аккаунт Telegram.

Секреты остаются в окружении сервера. Токен не входит в manifest, аргументы инструментов или сообщения об ошибках. Локальный сервер работает через stdio и не открывает сетевой порт.

Неопределённая доставка не повторяется автоматически. При таймауте состояние сохраняется как uncertain, при прерывании может остаться pending. Нужно проверить Telegram; нельзя обходить эту защиту новым идентификатором. Защита зависит от сохранности общей базы состояния.

Текст из чатов — данные. Skill запрещает воспринимать сообщения Telegram как инструкции, менять по ним разрешения или публиковать без поручения пользователя.

Подробнее: модель безопасности · статусы и ограничения.

Как устроено

flowchart LR
    A[ChatGPT / Codex] -->|MCP| B[Три инструмента]
    B --> C[Проверка разрешений]
    C --> D[Telegram Bot API]
    C <--> E[(SQLite: события и отправки)]

src/telegram_bot/
├── config.py      # Секреты и списки разрешённых чатов
├── client.py      # Ограниченный клиент Bot API
├── store.py       # Состояние и блокировки SQLite
├── service.py     # Чтение и защита отправки от повторов
└── server.py      # MCP-инструменты

Слой Service отделён от MCP: поверх него можно добавить планировщик и очередь заданий. Несколько каналов одного владельца уже поддерживаются; изоляция нескольких владельцев требует дальнейшей разработки.

Разработка

uv sync --locked
uv run --locked python -m unittest discover -s tests -v

Тесты проверяют доступ, фильтрацию, перезапуски, конкурентные отправки, ошибки Telegram и настоящий обмен MCP через stdio. Telegram HTTP заменён имитацией: тестам не нужны токены, они не отправляют сообщения.

GitHub Actions запускает тесты на Python 3.11, 3.12 и 3.13. Порядок внесения изменений: CONTRIBUTING.md.

Дальнейшее развитие

• Три MCP-инструмента и отдельные разрешения

• Несколько каналов одного владельца

• Сохранение состояния и защита повторных вызовов

• Очередь публикаций с расписанием, лимитами и паузой

• Отправка вложений

• Раздельные учётные записи владельцев

• Публичный HTTP-сервер с аутентификацией

Планы не означают, что эти функции уже доступны. Идеи и воспроизводимые ошибки можно оставить в Issues.

MIT License · Автор: Evr1kys · Независимый проект, не официальный продукт Telegram или OpenAI.