МессенджерыTelegram

MCP-сервер Telegram для Claude Code и Cursor

Подключите MCP-сервер Telegram к Claude Desktop, Cursor или другому MCP-приложению, выберите, что агенту можно читать и отправлять, и проверьте его инструменты.

MCP и навыки →Что MCP даёт агенту, как подключить свой клиент и как читать эти доки.

Это техническая справка по подключению клиента к этому мессенджеру через MCP. Здесь можно проверить инструменты, настройки и права; выбрать и настроить первое подключение поможет общая инструкция ниже.

Выбрать способ подключения →

Эта страница полезна, если вы хотите, чтобы приложение агента без терминала работало с вашим Telegram, например Claude Desktop или чат в Cursor. Это также помогает, когда вы хотите, чтобы само приложение спрашивало вас перед каждым действием. Прочитав эту страницу, вы сможете подключить приложение к своему аккаунту, выбирать, что может делать агент, а также использовать готовые запросы и упоминания в чате.

Сначала несколько терминов:

  • MCP (Протокол контекста модели) — это стандарт, по которому приложение ИИ использует внешние инструменты. Приложение является клиентом MCP; tg personal mcp serve — это сервер MCP.
  • Инструмент — это одно действие, которое сервер предлагает агенту, например «чтение» или «запись».
  • Готовый запрос — это готовая задача, которую приложение отображает в виде команды, например «Просмотреть непрочитанные чаты».
  • Ресурс — это данные, которые приложение может прикрепить к разговору, например один чат.
  • Профиль — это один набор настроек и один логин в tg; см. профили.

Сервер поставляется с tg; больше нечего устанавливать. По умолчанию он обращается к приложению через стандартный ввод и вывод. Вместо этого tg personal mcp serve --http --public-url передает его через локальный порт за вашим туннелем HTTPS.

Нужен ли вам MCP?

ИИ-агент, который может запускать команды в терминале (например, Claude Code, Codex, агент Cursor или Gemini CLI), не нуждается в MCP. Он напрямую вызывает tg, через интерфейс командной строки; он узнает, как это сделать, благодаря навыку, который печатает tg skill show. MCP предназначен для:

  • приложения без терминала, такие как Claude Desktop или чат Cursor;
  • всем, кто хочет, чтобы приложение спрашивало перед каждой отправкой.

Для ChatGPT или Claude в браузере используйте tg personal mcp serve --http — см. подключение браузера или приложения для телефона.

Что дает сервер

ЧтоЧто он делает
Три инструментаНайдите команду, затем запустите ее для чтения или записи
Шесть готовых запросовУзнавайте, отвечайте, находите, просматривайте, открывайте задачи, связывайте беседы
Чаты @Прикрепить чат и его последние сообщения к беседе
Навык, tg://skillТот же текст, что и у tg skill show
ДиаграммыСтатистика чата в формате JSON или PNG
РазрешенияПрофиль решает, какие команды видит агент

Персональные инструменты используют тот же каталог, что и max. В Telegram тоже есть темы.

Подключение

Сначала запустите tg personal setup --agent none в локальном терминале. Он входит в ваш аккаунт Telegram. Сервер MCP никогда не входит в систему вместо вас. Затем tg personal mcp add подключает приложение в качестве отдельного шага. Агент может прочитать tg skill show до того, как вы войдете в систему; это объясняет оба шага.

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

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

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

mcp check не читает сообщения и не авторизуется в Telegram. Хороший результат означает, что согласование MCP и список инструментов работают. Это не означает, что сессия аккаунта действительна. potential_writes подсчитывает инструменты, не помеченные как доступные только для чтения. Когда сервер не запускается, ошибка показывает последние строки, записанные в stderr, с замаскированными домашним каталогом, длинными числами и токенами. Приложениям браузера и телефона требуется отдельное удаленное подключение (подключение приложения браузера или телефона).

Claude Code, вручную:

claude mcp add tg -- tg personal mcp serve

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

claude mcp add tg-work -- tg work mcp serve

Один сервер может работать с несколькими профилями. Перечислите их в --profiles или укажите --profiles all для всех профилей. Тогда каждый вызов инструмента называет свой профиль:

claude mcp add tg -- tg mcp serve --profiles personal,work
claude mcp add tg -- tg mcp serve --profiles all

tg mcp serve без профиля и без --profiles отказывается запускаться и перечисляет ваши профили: сервер никогда не выбирает профили за вас. Строка, которую он пишет в stderr при запуске, называет профили, с которыми он работает. mcp config, mcp revoke, --http и mcp server start|stop|status принимают тот же выбор.

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

tg personal mcp config
tg work mcp config                  # another profile
{
  "mcpServers": {
    "tg-personal": {
      "type": "stdio",
      "command": "/usr/bin/node",
      "args": ["/usr/lib/node_modules/@wirecat/tg-cli/dist/bin/tg.js", "personal", "mcp", "serve"],
      "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, его путь принадлежит одной версии Node. Запустите tg personal mcp config еще раз после его изменения. При запуске из npx команда отказывается: npx очищает свой кеш, и путь перестает существовать.

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

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

У бота есть собственный сервер tg <name> bot mcp serve; см. бот для агента.

Разрешения агента

permissions профиля определяет доступ (что профиль может делать). deny блокирует команду, readonly разрешает только чтение, а ask или allow разрешает запись, запрошенную агентом. Сервер не показывает запросы подтверждения: настройте одобрение в приложении агента. В терминале команда ask все еще требует вашего подтверждения. С JSON или --no-input вопросов нет, поэтому запись будет запрещена, если вы не добавите --yes.

tg agent config set permissions.messages readonly
tg agent config set permissions.messages.send allow

Здесь agent — имя профиля. При записи сохраняются лимиты получателей, почасовые лимиты и журнал отправки (tg personal sends list). Маркировка чтения — это отдельная запись под chats.mark-read. Удаление через MCP удаляет сообщения только для вас, максимум десять за раз; агент никогда не удаляет сообщения для всех, а каналы и супергруппы, не позволяющие удалять только для себя, получают отказ. --permission key=level ужесточает уровень только для этого серверного процесса и никогда его не ослабляет.

Инструменты

Покрытие команд. Эти инструменты дают агенту доступ к большинству повседневных операций командной строки: сообщениям, чатам, контактам, вложениям, анализу обсуждений и статистике. Инструмент поиска возвращает доступные команды с параметрами и последствиями; набор определяется поддержкой мессенджера и правами профиля. Точный синтаксис и параметры — в полном справочнике команд. Выполняйте команду, предложенную каталогом, через инструмент чтения или изменения; вход в аккаунт и интерактивная установка выполняются в терминале.

ИнструментЧто он делает
tg_tools_searchНайдите команду, ее аргументы и ее эффекты
tg_readЗапустите команду чтения, предложенную поиском
tg_writeЗапустите команду записи, предложенную поиском

Оба инструмента запуска используют {command, arguments}. Используйте путь к команде, который вернул поиск:

{"command":"stats chats show","arguments":{"chat":"123"}}

status считывает состояние профиля через tg_read. Поиск показывает только то, что позволяют разрешения профиля и Telegram. Бот-серверы используют tg_bot_tools_search, tg_bot_read и tg_bot_write; их пути команд не включают bot.

Ответы структурированы в формате JSON: списки сохраняют свои страницы, а идентификаторы остаются строками. Ошибка — {error:{code,reason,message,details}}; для цели, соответствующей нескольким чатам, кандидаты приходят в details.candidates. Сервер проверяет аргументы на соответствие схеме команды и отклоняет неизвестные поля перед подключением или действием. Используйте at_time для планирования. Если результат записи неизвестен, проверьте журнал отправки и Telegram, прежде чем думать о повторной попытке. Текст сообщения — это данные, а не инструкции для агента. Схемы, ограничения и правила повтора находятся в как tg ведет себя в скриптах.

Что доступно агенту

Список команд сохраняет команды, запрещённые разрешениями. И полный список, и поиск возвращают availability: { available: false, reason, permission }, когда команда закрыта; разрешённые команды возвращают availability: { available: true }. Агент видит команду и её аргументы, но выполнить её без разрешения не может. Доступность следует текущим настройкам, и каждый вызов снова проверяет разрешения. --help в CLI и commands --json тоже показывают все команды независимо от разрешений профиля. С указанным профилем они показывают и текущую доступность; список без профиля не зависит от настроек аккаунта.

Команды, которые сервер не предлагает

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

  • Вход и настройка: setup, session start|end, complete, mcp config|add|check|revoke, bot auth set|show|remove, bot mcp config. Агент не может их вызвать, или для них нужны вы за клавиатурой. mcp и bot mcp сами по себе только печатают справку.
  • Удаление аккаунта: account remove завершает сессию профиля и забывает его на этом компьютере, поэтому её запускаете только вы.
  • Долгие команды: watch, serve и bot watch работают, пока вы их не остановите, а вызов агента должен завершиться. Сам сервер MCP (mcp serve, bot mcp serve) не предлагается по той же причине, как и mcp server и mcp server start|stop|status, которые запускают его в фоне.

У команд store backup|restore, server start|stop|restart, загрузки моделей, schedule run|exec, doctor reports create и account sessions end есть собственные ключи разрешений со значением ask по умолчанию. Сервер предлагает их агенту; подтверждениями управляет приложение MCP. В tg commands --json команда, не предлагаемая через MCP, отмечена mcp: false, а у долгой команды вместо этого есть поле lifetime. Прямым операциям bot api требуется отдельное разрешение.

Команды, которые меняют возможности следующего запуска

config set|unset, recipients add|remove|clear, chats rules set|unset, правила и согласия replies, schedule command|agent|remove, server install|uninstall, skill install, attachments jobs install|start|stop|uninstall, models keys set|remove, flood clear, upgrade (upgrade --check только проверяет и не ограничивается), а у бота recipients add|remove|clear и chats rules set|unset остаются в списке команд вместе с аргументами. Выполнить их можно, только если профиль устанавливает permissions.mcp.authority в allow или ask. По умолчанию это deny: список помечает их недоступными, называет разрешение и объясняет причину; вызов отклоняется. Иначе агент, ограниченный чтением, мог бы разрешить изменения следующему запуску. Агент не может сам установить этот ключ: config set тоже им закрыт. Меняйте его в своём терминале, вне агента: config set, запущенный в оболочке агента (где задана AI_AGENT, CLAUDECODE или OPENCLAW_SHELL=exec), для этого ключа тоже отклоняется. Делайте это только для профиля, агенту которого доверяете:

tg agent config set permissions.mcp.authority allow

Подробнее — в разрешениях.

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

Сервер предлагает шесть готовых запросов; в Claude Code это команды /:

Готовый запросАргументЧем занимается агент
catch-upkind, mode — опциональновызывает tg_read (command: "inbox"); mode — unread (по умолчанию), new или время; kind выбирает виды чата; для маркировки чтения требуется отдельный утвержденный вызов инструмента
replychatчитает чат, пишет черновик и отправляет его только после того, как вы одобрите этот текст
findtextищет человека или слова и показывает сообщения вокруг каждого попадания; ничего не отправляет
link-conversationsнетсообщает стоимость и запрашивает ваше согласие, затем читает батчи, сохраняет ссылки и перестраивает (ниже)
reviewsince, groups — опциональновызывает tg_read (command: "review") один раз и сортирует его на то, что вы должны, что должны другие и что нужно уточнить; создает черновики напоминаний, отправляет одно только после вашего «да»
open-taskschat — опциональновызывает проверку для обновления задач, перечисляет открытые задачи и предлагает черновики; закрывает задачу только после вашего одобрения; ничего не отправляет

reply и review отправляются через tg_write (command: "messages send"). Таким образом, если messages.send — readonly, агент показывает только черновики.

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

tg_read (command: "messages link") возвращает { item: { ref, url, access, reason } } без текста сообщения. Аккаунт и аудиторию проверяет так же, как messages link; частная ссылка никого не делает участником. Контрольные точки inbox и review в MCP отделены от контрольных точек --new терминала.

Диаграммы статистики

tg_read (command: "stats charts") считывает статистику чата из локальной копии и возвращает chart в формате JSON. Для изображения добавьте format: "png": ответ — темный PNG плюс JSON с данными chart и размером image. Без format ответ останется JSON. Инструмент не подключается к Telegram и не записывает файлы; для этого требуется разрешение messages. Вступления и выходы (membership) здесь недоступны.

Связывание разговоров

Готовый запрос link-conversations позволяет агенту связывать ответы с беседами. Агент сначала сообщает размер работы с tg_read (command: "conversations batches status") и ждет вашего согласия. Затем он считывает пакеты с помощью tg_read (command: "conversations batches show"), сохраняет ответы с помощью tg_write (command: "conversations links add") и перестраивает с помощью tg_write (command: "conversations links rebuild"). tg_write (command: "conversations links clear") удаляет ответы агента; после этого тоже нужно пересобрать связи. Для сохранения требуется разрешение conversations.links. Если вы настроили внешнюю службу для векторов поиска, поиск MCP также отправляет текст запроса в эту службу.

Файлы и сохраненные сообщения

tg_read (command: "attachments list") показывает пути к сохраненным файлам и то, был ли извлечен их текст. tg_write (command: "attachments update") сохраняет текст, прочитанный агентом, из файла. Извлечением текста управляют разрешения профиля на вложения. tg_read с command: "messages context" и arguments: { offline: true } считывает только локальную копию.

Работа соединения

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

Через стандартный ввод и стандартный вывод сервер завершает работу, как только приложение закрывает стандартный ввод, и закрывает соединение с Telegram. По HTTP он работает до нажатия Ctrl-C. tg personal mcp revoke завершает каждый вход в систему в браузерном приложении и сохраняет сессию Telegram. См. подключение браузера или приложения для телефона.