MCP-сервер

tg mcp предоставляет агенту доступ к профилю по MCP через stdin и stdout, без сетевого порта. Сервер входит в tg; отдельная установка не нужна.

Когда нужен MCP. В Claude Code, Codex и других агентах с терминалом достаточно tg: возможности и расход токенов те же. MCP нужен клиентам без терминала, например Claude Desktop или чату Cursor, и для подтверждения отправок в интерфейсе клиента. ChatGPT или Claude в браузере требуют дополнительной настройки: Удалённый доступ.

Сервер основан на реализации max-cli (max mcp) и ведёт себя аналогично.

ПодключениеCopy Anchor Link

Сначала выполните tg setup --agent none в локальном терминале: эта команда настраивает аккаунт Telegram. tg mcp setup отдельно подключает клиент. tg skill show объясняет оба шага до входа. Сам MCP-сервер не выполняет вход за вас.

Codex или Claude Code на этом компьютере:

tg mcp doctor                # check that MCP starts and lists tools
tg mcp setup codex          # add it to Codex
tg mcp setup claude-code    # or add it to Claude Code

Укажите профиль первым, например tg work mcp setup codex. Настройка использует собственную команду клиента и не меняет другие серверы. Если сервер с таким именем уже есть, удалите его запись в клиенте перед повторной настройкой. Стандартный профиль tg предлагает инструменты изменения данных, поэтому настройка просит проверить разрешения и повторить команду с --allow-writes. Этот флаг подтверждает установку, но не меняет разрешения. Чтобы ограничить действия агента, сначала задайте permissions профиля (ниже).

mcp doctor не читает сообщения и не входит в Telegram. Успешная проверка означает, что подключение MCP и список инструментов работают; она не подтверждает действительность сессии аккаунта. potentialWrites считает инструменты без объявления «только чтение». Для браузера и мобильных чатов требуется отдельное удалённое подключение (инструкция).

Claude Code:

claude mcp add tg -- tg mcp

С профилем — имя ставится первым, как в обычной команде:

claude mcp add tg-work -- tg work mcp

Claude Desktop, Cursor и другие: tg выводит запись для файла настроек клиента:

tg mcp config
tg work mcp config --confirm-send     # the entry with a form before every change

--confirm-send, --allow-dangerous и --yes включаются в запись как указаны (ниже).

{
  "mcpServers": {
    "tg": {
      "type": "stdio",
      "command": "/usr/bin/node",
      "args": ["/usr/lib/node_modules/@leemour/tg-cli/dist/bin/tg.js", "mcp"],
      "env": { "XDG_RUNTIME_DIR": "/run/user/1000" }
    }
  }
}

Вставьте запись в mcpServers: Claude Desktop использует ~/Library/Application Support/Claude/claude_desktop_config.json в macOS и %APPDATA%\Claude\claude_desktop_config.json в Windows; Cursor — ~/.cursor/mcp.json. Команда сама не записывает файл.

Пути абсолютные: приложение, запущенное с рабочего стола, не видит PATH терминала. В Windows tg — файл tg.cmd, который клиент без оболочки не может запустить напрямую. Запись копирует заданные TG_CONFIG_DIR, TG_STATE_DIR, TG_CACHE_DIR, MESSAGING_STORE, XDG_RUNTIME_DIR, но никогда TG_API_ID, TG_API_HASH или сессию.

Если Node установлен через nvm, fnm или Volta, путь привязан к его версии: после смены повторите tg mcp config. Запуск из npx отклоняется, поскольку очистка кеша npx удалит путь.

⚠ TG_CONFIG_DIR, TG_STATE_DIR и TG_CACHE_DIR меняют место поиска сессии. Разные значения в терминале и MCP-клиенте приводят к сообщению «нет сессии», хотя tg работает в терминале. Задайте одинаковые значения в обоих окружениях или не задавайте нигде.

⚠ В Linux доступ к данным приложения в хранилище ключей зависит от XDG_RUNTIME_DIR. Клиент с сокращённым окружением может убрать переменную; тогда инструменты сообщают о недоступном хранилище. tg mcp config включает её в запись.

Разрешения агентаCopy Anchor Link

permissions профиля определяет доступные инструменты по тем же уровням, что команды (Настройки):

По умолчанию агент может отправлять, редактировать, ставить реакции, пересылать, закреплять, голосовать и отмечать прочитанным без параметра или подтверждения. Только tg_messages_delete имеет уровень ask: перед каждым удалением появляется форма. Агент никогда не удаляет у всех и не завершает другие сессии независимо от уровня.

Для чтения выделите агенту отдельный профиль: tg agent session start создаёт ещё одну сессию того же аккаунта. Настройте в нём каждый ресурс:

for key in messages reactions polls topics chats contacts account; do
  tg agent config set permissions.$key readonly
done
claude mcp add tg -- tg agent mcp

Старая настройка readOnly: true делает то же. Чтобы запрашивать подтверждение каждой отправки, задайте messages.send уровень ask:

tg agent config set permissions.messages.send ask

Ограничения действуют и на вас: tg agent messages send тоже спросит подтверждение. Два параметра пропускают форму для уровня ask:

• tg mcp --allow-dangerous — без формы перед удалением;
• tg mcp --yes — без формы перед другими изменениями.

Отправка, редактирование и пересылка через MCP проверяют permissions, получателей, часовой лимит и журнал (tg sends list), как обычные команды. Инструменты изменения также отмечены опасными: VS Code и Cursor запрашивают подтверждение каждого вызова; по документации Claude Code показывает диалог даже при предварительном разрешении.

Отметка прочитанным — chats.mark-read: собеседник видит прочтение. Задайте readonly, если агент не должен выдавать просмотр. tg_chats_mark_read не входит в часовой лимит.

Удаление — messages.delete. tg_messages_delete удаляет до 10 сообщений только из вашего вида. Удаление у всех доступно только вашей команде в терминале. В супергруппах и каналах Telegram не поддерживает удаление только для себя: инструмент там отклоняется.

--allow-send, --allow-mark-read и --allow-delete больше не влияют на разрешения. Они принимаются с предупреждением для совместимости; удалите их из настроек клиента.

Форма подтверждения сервераCopy Anchor Link

claude mcp add tg -- tg mcp --confirm-send

Перед изменением с уровнем ask, а с --confirm-send — перед любым изменением, сервер показывает форму. При отправке в ней указаны чат (название и идентификатор, найденные по аргументу агента) и полный текст. Действие выполняется только после Accept; полей ввода нет. Окно клиента показывает исходные аргументы модели (chat: "Anna"), а форма — фактического получателя («Anna Petrova (123456)»).

• Отказ или закрытие: изменений нет; агент получает confirmation_required и не должен повторять запрос.
• Клиент без поддержки форм получает ошибку: изменений нет. Claude Code поддерживает формы.
• Подтверждение связано с показанными данными: при смене чата, текста или инструмента действие не выполняется.
• Подтверждение действует один раз, пять минут. Повторное использование ничего не меняет.

ИнструментыCopy Anchor Link

Ответы соответствуют --json команд: список — { items, page, limit, hasMore }, сообщения чата — { items, limit, hasMore }, идентификаторы — строки. Ошибка — { error: { code, message, … } } с кодами CLI; неоднозначное название возвращает candidates.

Чтение Telegram сохраняется в базу; пакет исходных данных читает этот архив. Вызовы можно записывать как запуски (tg runs list) с именами mcp chats list и подобными.

Готовые запросы и чаты через @Copy Anchor Link

Сервер предоставляет четыре готовых запроса; в Claude Code они доступны как команды /:

reply и review отправляют через tg_messages_send. При messages.send уровня readonly агент только показывает черновики.

Чаты доступны как ресурсы tg://chat/<id>; в Claude Code их можно упоминать через @. Ресурс содержит чат и недавние сообщения. Список читается из базы без подключения к Telegram и пуст, пока ничего не прочитано. Подключение требуется при чтении конкретного чата.

Работа соединенияCopy Anchor Link

Первый вызов подключается к Telegram, следующие используют соединение. Оно закрывается после двух минут без вызовов и в любом случае через пять минут после открытия, чтобы длительная сессия не читала устаревшие данные. Следующий вызов подключается заново. Вызовы выполняются по одному даже при одновременной отправке клиентом.

При закрытии stdin клиентом сервер завершается и закрывает подключение к Telegram.