tg-mcp

MCP-сервер поверх личного Telegram-аккаунта: 79 инструментов, MTProto, не Bot API.

---

English

What it is. tg-mcp gives an MCP client — Claude Code, Claude Desktop or anything else that speaks MCP — access to your personal Telegram account: read any chat, search the whole history, look at photos, listen to voice messages, send as yourself, manage groups and forums. It speaks MTProto through Telethon, not the Bot API, so it sees the entire account, not just messages addressed to a bot.

How it works. A daemon owns the Telegram session and does all the work; the MCP server is a thin stdio process that forwards calls to it over a unix socket. The same daemon also works while no agent is running: alerts about incoming messages to your own bot, a scheduled digest, inbox filters and reminders. Because of that unix socket, the supported systems are macOS and Linux — on Windows use WSL or Docker.

Quick start (needs Python 3.11+ and uv):

git clone https://github.com/draiqw/tg-mcp && cd tg-mcp
uv sync
uv run tg init      # one wizard: keys, login, bot, daemon, MCP registration, subagents

tg init asks only for what is missing, so running it again is safe and doubles as a repair command. Only the API keys and the login itself are mandatory — everything else is skipped with Enter, and the wizard says what stops working without each piece. The login code and the 2FA password are typed by you and are never stored. uv run tg doctor prints the state of an existing install.

Before you run it. This is a personal tool, not a hosted service, and it holds a real account. data/session.session is full access to that account without password and without 2FA; the local index and the per-chat dossiers put message text on disk; the dossier feature sends chat content to an external model. Read SECURITY.md first — it is short.

What it costs. Nothing by default. Two optional features can: the per-chat dossiers call an external model, billed per token — off until you turn them on, and capped per hour when you do; and Groq transcription is free only within its rate limits. Telegram's own transcription needs Premium, and the local Whisper model costs disk and CPU rather than money.

When something breaks, start with uv run tg doctor and docs/troubleshooting.md.

The rest of the documentation is in Russian: docs/tools.md (every tool), docs/architecture.md, docs/configuration.md, docs/mcp.md, docs/troubleshooting.md, docs/security.md. MIT licensed.

---

Что это

Обёртка над личным Telegram-аккаунтом, которая отдаёт его агенту как набор инструментов MCP. Работает поверх MTProto (Telethon), а не Bot API, — поэтому видно весь аккаунт целиком, а не только то, что написали боту. Это личный инструмент под один аккаунт и одного владельца, а не сервис: он держит живую сессию Telegram на твоей машине и от твоего имени пишет живым людям.

Разница с обёртками над Bot API принципиальная, а не количественная. Бот видит только адресованные ему сообщения, не может прочитать переписку с человеком, не имеет истории и не существует до того, как ему нажали Start. Здесь у агента тот же доступ, что у тебя в приложении: все диалоги, поиск по всей переписке, вложения, папки, черновики, отправка от твоего имени. Цена этого — раздел «Риски» ниже, и читать его надо до запуска, а не после.

Что умеет

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

Разбор входящих не сводится к непрочитанному: tg_pending показывает оборванные разговоры — кому не ответили и кто не ответил, включая прочитанное-и-забытое, которого в счётчике непрочитанного уже нет. tg_person собирает досье на человека одним вызовом: профиль, флаги, общие чаты, место в топе собеседников, история личной переписки. tg_memory ведёт постоянное досье на чат, чтобы незнакомый разговор начинался не с тысячи сообщений истории.

Демон умеет и то, для чего Claude запускать не нужно: алерты о важных входящих в твоего бота, сводку по расписанию (digest_at), почтовые фильтры входящих (пометить прочитанным, в архив, заглушить, в папку, в Избранное) и напоминания, переживающие перезапуск. Автоответов среди действий фильтров нет намеренно: правило работает без надзора и не должно уметь написать постороннему человеку.

По названным владельцем чатам поднимается локальный полнотекстовый индекс (tg_index, sqlite + FTS5): тогда tg_search(engine="local") ищет мгновенно и умеет то, чего у серверного поиска нет вовсе — фильтр по автору, срез «всё от такого-то за период», ранжирование по релевантности и подсветку совпадения.

Полный справочник — docs/tools.md.

Что внутри

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

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

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

Нужен Python 3.11 или новее и uv. Планку держит ровно одна вещь — datetime.UTC, алиас из 3.11; ничего из 3.12 и 3.13 в коде нет. Система — macOS или Linux: MCP-сервер разговаривает с демоном по unix-сокету, поэтому Windows не поддерживается (в WSL или docker работает).

Каталог любой: проект берёт пути от себя самого, и все команды, которые он печатает, уже содержат настоящий путь до этой копии.

git clone https://github.com/draiqw/tg-mcp && cd tg-mcp
uv sync
uv run tg init

tg init — мастер, который доводит установку до рабочего состояния: ключи приложения, вход в аккаунт, бот уведомлений, демон, регистрация MCP-сервера в Claude Code и субагенты в ~/.claude/agents. Каждый шаг объясняет, зачем он и что перестанет работать без него.

Три свойства мастера стоит знать заранее:

• Обязательны только api_id/api_hash и вход. Бот, ключи моделей, локальная расшифровка и автозапуск пропускаются по Enter.
• Код из Telegram и облачный пароль 2FA вводишь ты. Мастер их не запрашивает, не подставляет и не хранит — он передаёт этот шаг в tg login.
• Повторный запуск безопасен. Мастер сначала смотрит, что уже сделано, и делает только недостающее, поэтому годится и как «почини мне установку».

Что понадобится по дороге: приложение на my.telegram.org → API development tools (оттуда api_id и api_hash; без них доступен только Bot API, то есть свои чаты не видны) и, если нужны алерты, отдельный бот у @BotFather — переиспользовать существующего нельзя, его сообщения станут для тебя входящими и вызовут алерт на алерт.

В конце мастер печатает tg capabilities: что доступно, что заблокировано и чем именно. Состояние уже поставленного разбирает uv run tg doctor — что стоит, что запущено, где лежат файлы и какие у них права, отвечает ли демон, зарегистрирован ли MCP, совпадают ли субагенты с репозиторием. В его выводе нет ключей, телефона и имени аккаунта, поэтому его можно целиком приложить к issue. Если после него что-то всё равно не работает — docs/troubleshooting.md: там частые поломки перечислены такими, какими они видны снаружи.

Если хочется по шагам

Мастер ничего не делает сам — он вызывает те же команды, и любую из них можно выполнить отдельно:

cp .env.example .env && chmod 600 .env
uv run tg setup        # api_id/api_hash и токен бота, скрытым вводом
uv run tg login        # телефон, код из Telegram, облачный пароль при 2FA
uv run tg link-bot     # нажми Start в чате с ботом, команда запомнит твой chat_id
uv run tg daemon start # демон владеет сессией; без него инструменты не работают
uv run tg status       # что настроено, что нет, живой ли демон
claude mcp add -s user telegram -- uv --directory "$PWD" run tg-mcp
cp agents/*.md ~/.claude/agents/

Дальше — docs/mcp.md: область видимости, Claude Desktop, готовые субагенты, диагностика. Настройки алертов, фильтров и лимитов — docs/configuration.md.

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
claude mcp add telegram -- docker exec -i tgagent tg-mcp

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

Сколько это стоит

Сам агент бесплатный, и в базовом виде платить некому: MTProto, бот уведомлений, серверный поиск, локальный индекс, алерты, дайджест, фильтры и напоминания денег не стоят. Счёт может появиться ровно в двух местах, и оба требуют ключа, которого по умолчанию нет:

• Досье на чаты (tg_memory) ходит во внешнюю модель и оплачивается по токенам — по умолчанию gpt-4o-mini по ключу OPENAI_API_KEY. Это единственное, что тратит деньги само, без запущенного Claude, и потому ограничено сразу трижды: без ключа инструмент отказывается, автообновление выключено, а включённое упирается в потолок в час (memory_max_per_hour, по умолчанию 10). TG_MEMORY_BASE_URL уводит вызовы в любой совместимый сервис, в том числе локальный, — тогда бесплатно.
• Расшифровка звука (tg_transcribe) — три движка с разной ценой. Встроенная в Telegram считается на его серверах и по-настоящему доступна с Premium (без подписки Telegram даёт небольшую бесплатную квоту). У Groq бесплатный уровень ограничен числом запросов, выше него — платный план. Локальная модель денег не стоит вовсе: цена в полутора гигабайтах весов и во времени счёта.

Токены самого Claude сюда не относятся — их считает твой клиент, а не агент. Ключи и потолки — в docs/configuration.md.

Риски

Прочитай до запуска, а не после. Полностью — в SECURITY.md и docs/security.md.

• data/session.session — это вход в аккаунт без пароля и без 2FA. Скопированный файл равен угнанному аккаунту. Он закрыт .gitignore и .dockerignore, но за бэкапы и синхронизацию каталога в облако отвечаешь ты.
• Агент пишет живым людям. При TG_ALLOW_WRITE=1 он отправляет сообщения от твоего имени, и получатель не знает, что писал не ты.
• Локальный индекс и досье кладут переписку на диск, а обновление досье отправляет её во внешнюю модель. Ни то, ни другое не включается само: чат приходится назвать явно, и каждый такой вызов попадает в аудит.
• Промпт-инъекции — открытая проблема. Чужие сообщения объявлены данными в промптах субагентов и никогда не интерпретируются кодом, но гарантией это не считается: под этим стоят лимиты, аудит и урезанный набор инструментов у дешёвого наблюдателя.
• В чате есть второй человек, который на всё это не подписывался.

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

• 60 сообщений в час, максимум 15 разных чатов в час (анти-рассылка), 50 удалений в час
• TG_ALLOW_WRITE=0 полностью выключает запись
• confirm_writes — средний режим: каждое пишущее действие спрашивает владельца в боте, молчание считается отказом. Правится только файлом: агент не должен уметь снять с себя ограничение
• каждое пишущее действие пишется в data/actions.jsonl и читается tg_actions
• фильтры входящих не умеют отправлять живым людям: список действий закрыт
• неоднозначное имя чата не угадывается: инструмент возвращает список кандидатов
• FloodWait от Telegram возвращается понятной ошибкой, а не падением

Команды

uv run tg init                        # мастер установки, он же «почини установку»
uv run tg doctor                      # диагностика: что стоит, что сломано, что делать
uv run tg status                      # что настроено, что нет, состояние демона
uv run tg capabilities                # что доступно, что нет и что с этим делать
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 run tg login --account work        # добавить второй аккаунт
uv run tg accounts --default work     # сменить аккаунт по умолчанию навсегда
uv sync --extra local-whisper         # локальная расшифровка звука (опционально)
uv run tg daemon start|run|stop|restart|status|logs
uv run tg call dialogs '{"limit": 5}' # дёрнуть метод демона мимо MCP
uv run tg logout                      # отозвать сессию и стереть файлы

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

Файл	О чём
docs/architecture.md	ядро, слои, инварианты, поток данных, что где лежит
docs/tools.md	справочник всех MCP-инструментов с параметрами
docs/configuration.md	переменные окружения, три режима записи, правила алертов, дайджест, фильтры входящих, несколько аккаунтов, лимиты
docs/mcp.md	подключение как MCP-сервер, субагенты, диагностика
docs/troubleshooting.md	что делать, когда не работает: tg doctor, частые поломки, куда смотреть
docs/docker.md	сборка, логин в контейнере, обновление, бэкап
docs/security.md	модель угроз: что защищено, что нет, как отозвать доступ

Участие и лицензия

Правки принимаются — как поднять окружение, что прогнать перед PR и почему возможность добавляется сразу в трёх местах, написано в CONTRIBUTING.md. Про уязвимости — SECURITY.md, публичный issue заводить не надо.

MIT, © 2026 Roman Akramov.