tg-agent

Полный доступ к личному Telegram-аккаунту для Claude Code и любого другого MCP-клиента: чтение всех чатов и структуры аккаунта, поиск по всей переписке, вложения, отправка от своего имени, черновики и отложенные сообщения, реакции, опросы, стикеры, нажатие кнопок у ботов, управление группами и форумами, несколько аккаунтов сразу и предупреждения через отдельного бота.

Агент не только читает переписку, но и смотрит картинки (tg_view отдаёт само изображение) и слушает звук: голосовые, кружки, музыка и видео расшифровываются в текст встроенной расшифровкой Telegram, через Groq Whisper или локальной моделью. Длинные посты пересказывает сам Telegram (tg_summarize), сторис читаются, не оставляя следа, а tg_wait и tg_ask дают агенту дождаться нужного сообщения или спросить разрешения у владельца прямо в боте.

Работает поверх MTProto (Telethon), а не Bot API — поэтому видно весь аккаунт, а не только сообщения, написанные боту.

Что внутри

MCP-клиент (Claude Code, Claude Desktop, любой другой)
        │  stdio
        ▼
tgagent.mcp_server ──unix socket──▶ tgagent.daemon ──MTProto──▶ Telegram
   70 инструментов     /data/daemon.sock    │
                                             ├─ watcher: входящие → правила → алерт
                                             └─ Bot API ──▶ твой бот ──▶ ты

Ядро — tgagent/core.py: один класс TelegramService, все операции с аккаунтом и все предохранители. Всё остальное — транспорт вокруг него. Подробнее: docs/architecture.md.

Быстрый старт (локально)

git clone <repo> ~/tg-agent && cd ~/tg-agent
cp .env.example .env && chmod 600 .env

uv sync
uv run tg setup     # api_id/api_hash с my.telegram.org + токен бота
uv run tg login     # телефон, код, при 2FA — облачный пароль
uv run tg daemon start
uv run tg status

Подключение к Claude Code:

claude mcp add telegram -- uv --directory ~/tg-agent run tg-mcp

Дальше — docs/mcp.md: область видимости, Claude Desktop, готовые субагенты, проверка что всё поднялось.

Быстрый старт (docker)

cp .env.example .env && chmod 600 .env   # заполни TG_API_ID / TG_API_HASH / TG_BOT_TOKEN
docker compose build
docker compose run --rm tgagent tg login # логин интерактивно, сессия ляжет в ./data
docker compose up -d

MCP-клиент подключается к тому же контейнеру:

claude mcp add telegram -- docker exec -i tgagent tg-mcp

Подробности, включая почему MCP запускается внутри контейнера, а не на хосте — docs/docker.md.

Документация

Команды

uv run tg status                      # что настроено, что нет, состояние демона
uv run tg setup                       # ключи и токен бота
uv run tg login                       # вход целиком
uv run tg send-code +7XXXXXXXXXX      # то же в три шага, без интерактива
uv run tg sign-in --code 12345
uv run tg password                    # облачный пароль 2FA, только с живого tty
uv run tg link-bot                    # привязать chat_id для алертов
uv run tg accounts                    # какие аккаунты залогинены
uv sync --extra local-whisper         # локальная расшифровка звука (опционально)
uv run tg login --account work        # добавить второй аккаунт
uv run tg daemon start|run|stop|restart|logs
uv run tg call dialogs '{"limit": 5}' # дёрнуть метод демона мимо MCP
uv run tg logout                      # отозвать сессию и стереть файлы

Предохранители

• 60 сообщений в час, максимум 15 разных чатов в час (анти-рассылка), 50 удалений в час

• TG_ALLOW_WRITE=0 полностью выключает запись

• каждое пишущее действие пишется в data/actions.jsonl

• неоднозначное имя чата не угадывается: инструмент возвращает список кандидатов

• FloodWait от Telegram возвращается понятной ошибкой, а не падением

• содержимое чужих сообщений в промптах субагентов объявлено данными, а не командами