telegram-mcp

Передаёт Claude самое новое изображение из одной группы Telegram.

Скриншоты публикует бот, а Telegram Bot API никогда не возвращает сообщения самого бота — поэтому этот инструмент читает группу через пользовательский аккаунт по MTProto (Telethon). Это единственный способ увидеть эти фотографии.

Настройка (один раз)

1. Получите api id и hash на https://my.telegram.org → API development tools.

2. Скопируйте cp .env.example .env и заполните TELEGRAM_API_ID, TELEGRAM_API_HASH и TELEGRAM_CHAT_ID (числовой id группы, отрицательный).

3. Создайте окружение:

python -m venv .venv
.venv\Scripts\pip install -e .[dev]

4. Войдите — в терминале, а не через Claude:

.venv\Scripts\telegram-mcp-login

Он запросит ваш номер телефона, код, который пришлёт Telegram, и ваш двухфакторный пароль, если он есть, а затем запишет session/telegram.session.

Он также один раз выводит список ваших диалогов и печатает название группы. Список позволяет сессии позже распознать супергруппу — Telegram превращает группу в супергруппу, как только в неё вступает бот, — а название подтверждает, что TELEGRAM_CHAT_ID указывает туда, куда вы думаете. Если группа не найдена, он сообщает об этом и завершается с ненулевым кодом.

Related MCP server: telegram-user-mcp

Установка в Claude

claude mcp add --scope user telegram -- <abs path>\.venv\Scripts\python -m telegram_mcp.server

Пользовательская область, поэтому каждый проект получает его.

Инструменты

• get_latest_image() — самое последнее фото в группе, просматривая последние 200 сообщений.

• wait_for_next_image(timeout_seconds=120) — блокируется, пока не появится фото новее момента вызова. Ожидание не тратит токены; процесс простаивает на сокете. Ограничено 1–240 с, чтобы оставаться в пределах тайм-аута инструмента MCP-клиента.

Оба возвращают изображение (JPEG, длинная сторона ≤1568 px) плюс строку текста: сначала путь к нетронутому оригиналу, затем id сообщения, временная метка, отправитель и подпись в кавычках. Обрежьте оригинал, если при уменьшении теряется мелкий текст.

Только один процесс может удерживать сессию одновременно. Если вторая сессия Claude Code вызывает инструмент, пока первая находится в середине вызова, ей сообщается повторить попытку через мгновение, а не выдаётся ошибка SQLite.

Тесты

.venv\Scripts\python -m pytest

Не требуется сеть и аккаунт Telegram — Telethon полностью имитируется.

Безопасность

session/telegram.session — это полный вход в ваш аккаунт Telegram. Он игнорируется git и никогда не покидает эту машину. Любой, у кого есть этот файл, может читать ваши сообщения; удалите его и повторите вход, если подозреваете, что он был скопирован. Учётные данные хранятся только в .env — никогда в документации, подсказках или тикетах.