Подключение ИИ-агентов к TrekMail через MCP

Сервер MCP от TrekMail позволяет совместимым ИИ-клиентам управлять почтовой инфраструктурой с помощью естественного языка. Его каталог охватывает домены, почтовые ящики, фирменное оформление и команды White Label, Drive, электронную почту, календарь, миграции, поддержку, оплату и связанные сервисы через единый API TrekMail.

Полный каталог загружается не в каждый диалог. TrekMail формирует tools/list на основе активных учетных данных: инструменты за пределами их областей доступа не включаются, как и инструменты, исключенные выбранным набором, режимом только для чтения, ограничениями транспорта или локальной настройкой безопасности. Поэтому учетные данные с узкой областью доступа к почте предоставляют компактный список почтовых инструментов.

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

Способы 1-3 используют OAuth 2.1: при первом подключении браузер открывает страницу согласия TrekMail, вы проверяете запрошенные разрешения, а клиент получает токен с областью доступа к вашей учетной записи. Долгоживущий токен tm_live_ не копируется в клиент. Любое подключение можно отозвать в разделе ИИ-агенты и API → Токены → Подключенные приложения.

Что вы получаете

• Отдельный набор инструментов для каждого подключения, который до регистрации фильтруется по разрешениям и настройкам безопасности текущего подключения.
• OAuth 2.1 + динамическая регистрация клиента: ИИ-клиент самостоятельно регистрируется, проводит вас через страницу согласия в браузере и получает токен с заданной областью доступа. Для веб-, настольного и CLI-способов не нужно копировать долгоживущие токены.
• Архитектура с двумя токенами: отдельный операционный токен для инфраструктуры и токен сообщений для всех операций веб-почты. При подключении через OAuth токены сообщений автоматически создаются для каждого ящика по мере необходимости.
• Автоматическая идемпотентность для требующих ее операций, поэтому повторная попытка не повторяет саму операцию.
• Удаление в два этапа: для удаления почтового ящика нужно явно выразить намерение и подтвердить его, после чего ящик перемещается в раздел недавно удаленных с возможностью восстановления.
• Средства безопасности при самостоятельном размещении: администратор собственного сервера MCP stdio может требовать одобрения операций удаления, отправки и миграции.
• Полный журнал аудита: каждая операция API и MCP регистрируется, записи хранятся 90 дней.

Перед началом

• Подключать агентов можно на всех тарифах.
  • Nano: инструменты проверки email. При добавлении хранилища Drive агент также получает предусмотренные для учетной записи функции Drive, включая просмотр, загрузку, общий доступ, восстановление и окончательное удаление.
  • Starter: полный доступ к Drive и проверке email, а также доступ только для чтения к остальным областям (домены, почтовые ящики, миграции, тикеты и другие). Используйте панель для недоступных через API на Starter операций записи, таких как создание миграций, ответы на тикеты или изменение автоответа.
  • Pro / Agency: полный доступ для чтения и записи ко всем семействам функций.
  • Пробный период или дополнение White Label: добавляет инструменты фирменного оформления, клиентов и команд, а также активности, пока право доступа активно. Без него эти схемы не включаются. В льготный период после отмены инструменты чтения получает только владелец.
• Подключаетесь впервые? Кнопка Начать обзор на странице ИИ-агенты и API знакомит с подключением агента, шагами для каждого клиента, ручными токенами, подключенными приложениями и журналом аудита.
• Для способов OAuth (1, 2, 3) создавать токен вручную не требуется. Клиент создает его в процессе авторизации в браузере. Для самостоятельно размещенного способа stdio (4) сначала создайте токен tm_live_ в панели.

1. Удаленный MCP-клиент (рекомендуется)

Используйте этот способ, если ИИ-клиент поддерживает удаленные серверы MCP и авторизацию в браузере.

Быстрый способ: вкладка Подключить агента на странице ИИ-агенты и API спрашивает, какой клиент вы используете, а затем показывает точный маршрут этого клиента, путь в меню или файл конфигурации и готовый фрагмент, в который уже подставлен ваш адрес. Если клиент есть в списке, следуйте этим указаниям вместо общих шагов ниже.

1. Откройте в клиенте настройки MCP, интеграций или коннекторов.
2. Выберите Добавить удаленный сервер MCP или Добавить пользовательский коннектор. Точное название зависит от клиента.
3. Введите:
   • Название: TrekMail
   • URL удаленного сервера MCP: https://trekmail.net/mcp
4. Подтвердите подключение. Браузер откроет страницу авторизации TrekMail.
5. Войдите, проверьте запрошенные разрешения и одобрите доступ. Вернитесь в клиент, когда браузер подтвердит подключение.

При первой авторизации выдается токен с ограниченным сроком действия. Совместимые клиенты обновляют его автоматически. Чтобы отключиться, используйте соответствующее действие клиента или отзовите приложение в разделе TrekMail Токены → Подключенные приложения.

2. CLI- или настольный клиент

Для клиента, принимающего команду stdio, используйте универсальный мост:

npx -y mcp-remote https://trekmail.net/mcp

Настройте эту команду как сервер MCP в клиенте. При первом подключении браузер откроется для авторизации.

Некоторые клиенты также предлагают собственную команду для добавления удаленного сервера MCP. Этот вариант тоже подходит: используйте https://trekmail.net/mcp в качестве URL сервера и следуйте подсказкам клиента.

Пример для конкретного клиента: Claude Code

claude mcp add trekmail https://trekmail.net/mcp -t http

Пример для конкретного клиента: Claude Desktop

Измените файл конфигурации (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json) и добавьте:

{
  "mcpServers": {
    "trekmail": {
      "url": "https://trekmail.net/mcp",
      "transport": "http"
    }
  }
}

Перезапустите Claude Desktop. При первом упоминании TrekMail в чате откроется окно OAuth.

Пример для конкретного клиента: Cursor

В Cursor нет отдельного экрана для удаленного сервера. Он читает ~/.cursor/mcp.json (или .cursor/mcp.json внутри проекта):

{
  "mcpServers": {
    "trekmail": {
      "url": "https://trekmail.net/mcp"
    }
  }
}

Пример для конкретного клиента: Windsurf

Windsurf читает ~/.codeium/windsurf/mcp_config.json. Обратите внимание: ключ называется serverUrl, а не url; удаленный сервер с настройкой url игнорируется:

{
  "mcpServers": {
    "trekmail": {
      "serverUrl": "https://trekmail.net/mcp"
    }
  }
}

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

3. mcp-remote (CLI)

mcp-remote удобен для тестирования и клиентов MCP не от Anthropic, которые еще не поддерживают удаленные серверы OAuth напрямую. Это небольшой мост Node между stdio и удаленным HTTP.

npx -y mcp-remote https://trekmail.net/mcp

При первом запуске браузер откроется для OAuth. Затем токен сохраняется в кеше в ~/.mcp-auth/ и используется автоматически.

Эту схему можно подключить к любому клиенту MCP stdio, указав команду mcp-remote вместо локальной точки входа Node.

4. Самостоятельно размещенный stdio (Claude Desktop / Docker / npm)

Если вместо OAuth нужны статические токены tm_live_, например для автономных серверов, частных экземпляров TrekMail или контейнерных развертываний, клонируйте и запустите пакет MCP stdio на своем хосте.

Сначала создайте токен API на странице ИИ-агенты и API → Токены. Для чтения и отправки email также создайте через API токен сообщений, используя операционный токен. Инструкции приведены на вкладке Подключить агента.

Установка сервера MCP

git clone https://github.com/trekmail/mcp-server trekmail-mcp
cd trekmail-mcp
npm install
npm run build

Claude Desktop (stdio)

Добавьте следующий блок в файл конфигурации MCP для Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "trekmail": {
      "command": "node",
      "args": ["./trekmail-mcp/build/index.js"],
      "env": {
        "TREKMAIL_BASE_URL": "https://trekmail.net",
        "TREKMAIL_API_TOKEN": "tm_live_your_token",
        "TREKMAIL_MESSAGE_TOKEN": "tm_msg_your_token",
        "TREKMAIL_ALLOW_SENDING": "false",
        "TREKMAIL_ALLOW_MIGRATION": "false"
      }
    }
  }
}

Измените путь в args, чтобы он указывал на каталог клонированного репозитория. Замените токены собственными. Можно не указывать TREKMAIL_MESSAGE_TOKEN, если нужны только инструменты инфраструктуры, или TREKMAIL_API_TOKEN, если нужны только инструменты сообщений. Требуется как минимум один токен.

Claude Code (stdio)

Добавьте этот блок в настройки MCP для Claude Code (.claude/settings.json или конфигурацию проекта):

{
  "mcpServers": {
    "trekmail": {
      "command": "node",
      "args": ["./trekmail-mcp/build/index.js"],
      "env": {
        "TREKMAIL_BASE_URL": "https://trekmail.net",
        "TREKMAIL_API_TOKEN": "tm_live_your_token",
        "TREKMAIL_MESSAGE_TOKEN": "tm_msg_your_token",
        "TREKMAIL_ALLOW_SENDING": "false",
        "TREKMAIL_ALLOW_MIGRATION": "false"
      }
    }
  }
}

Docker

Если вы предпочитаете Docker, соберите образ из репозитория и запустите его:

git clone https://github.com/trekmail/mcp-server trekmail-mcp
cd trekmail-mcp
docker build -t trekmail-mcp .

docker run -i \
  -e TREKMAIL_BASE_URL=https://trekmail.net \
  -e TREKMAIL_API_TOKEN=tm_live_your_token \
  -e TREKMAIL_MESSAGE_TOKEN=tm_msg_your_token \
  -e TREKMAIL_ALLOW_SENDING=false \
  -e TREKMAIL_ALLOW_MIGRATION=false \
  trekmail-mcp

Локальный npm (разработка)

git clone https://github.com/trekmail/mcp-server trekmail-mcp
cd trekmail-mcp
npm install && npm run build

TREKMAIL_BASE_URL=https://trekmail.net \
TREKMAIL_API_TOKEN=tm_live_your_token \
TREKMAIL_MESSAGE_TOKEN=tm_msg_your_token \
TREKMAIL_ALLOW_SENDING=false \
TREKMAIL_ALLOW_MIGRATION=false \
npm start

Переменные окружения stdio

Эти средства управления относятся только к самостоятельно размещенному процессу MCP stdio, который вы запускаете. Они не включают и не отключают функции продукта TrekMail.

Инструменты Drive для агентов

С операционным токеном, включающим области доступа Drive, сервер MCP предоставляет инструменты для пространств, использования, просмотра, загрузок, файлов, папок, корзины, массовых операций, публичных ссылок, управления паролями устройств синхронизации и состояния дополнения Drive. Подключение видит инструменты, разрешенные его областями доступа.

Для агента, работающего только с Drive, задайте TREKMAIL_API_TOKEN и предоставьте только необходимые рабочему процессу области доступа. При самостоятельном размещении stdio оставляйте разрушительные действия отключенными, если агент не выполняет проверенное задание окончательного удаления или очистки корзины. Покупка, изменение размера и отмена дополнения Drive не являются инструментами MCP; агенты могут читать состояние и цены дополнения, но изменения оплаты выполняются в панели.

Смотрите Обзор инструментов MCP для Drive и Подключение ИИ-агентов к TrekMail Drive.

Доступные инструменты

Сервер MCP предоставляет подключенным агентам следующие инструменты. Они регистрируются условно в зависимости от предоставленных токенов.

Какие из них агент действительно видит, определяют три фактора, применяемые до ответа tools/list:

1. Области доступа токена. Инструмент, возможность которого отсутствует в токене, никогда не регистрируется.
2. Локальные средства безопасности stdio. При самостоятельном размещении сервера stdio администратор может требовать одобрения операций записи, отправки или миграции. Размещенный MCP вместо этого использует области доступа, одобренные при OAuth.
3. TREKMAIL_READ_ONLY=true удаляет все инструменты записи независимо от областей доступа и флагов.

Таким образом, самостоятельно размещенное подключение можно намеренно ограничить, даже если токен имеет более широкие области доступа. Размещенный MCP остается ограничен разрешениями, одобренными при OAuth.

Инструменты доменов (операционный токен)

Сведения о поведении тарифов, состояниях ответа, безопасном удалении и правилах маршрутизации только для приема приведены в статье Псевдонимы доменов через API и MCP.

Инструменты White Label (операционный токен)

Набор white_label содержит 20 инструментов и появляется только тогда, когда это допускают право учетной записи, текущее членство и области доступа учетных данных. Фирменное оформление настраивается отдельно для каждого домена; остальные инструменты управляют настройкой, клиентами, доступом команды и активностью. Для записи требуется активный White Label. В льготный период после отмены инструменты чтения сохраняются только у владельца.

Агент может выполнить настройку бренда от начала до конца: задать бренд, скопировать возвращенные dns_records, опубликовать их с помощью apply_cloudflare_dns, а затем проверить и просмотреть состояние. Вызовы, изменяющие доступ, ограничены текущим членством и границей доменов вызывающей стороны, даже если токен запросил более широкие области. Смотрите Руководство по фирменному оформлению White Label через API и MCP и Управление командами White Label через API и MCP.

Инструменты DNS (операционный токен)

Инструменты почтовых ящиков (операционный токен)

Инструменты общих почтовых ящиков (операционный токен)

Общий почтовый ящик представляет собой командный адрес (support@, sales@), который участники открывают через собственную обычную учетную запись ящика в веб-почте и, если включено, через делегированный нативный доступ IMAP/SMTP. У него нет прямого входа по паролю. Доступ одинаков для всех: каждый может читать, а can_send является единственным переключателем (можно отвечать или доступ только для чтения). Ролей участников нет.

Жизненный цикл общих почтовых ящиков (операционный токен)

Три инструмента жизненного цикла и три инструмента записи для участников изменяют доступ. Администратор локально размещенного stdio может требовать TREKMAIL_ALLOW_DESTRUCTIVE=true, прежде чем они станут доступны; list_shared_mailbox_members работает только для чтения и доступен всегда.

После создания, преобразования или изменения членства вызовите get_mail_client_setup с ID обычного почтового ящика участника. Прочитайте shared_mailboxes.items[], дождитесь native_access_ready=true и проверьте send_as_ready перед настройкой отправки. Ответ содержит точные пути Входящие/Отправленные/Архив/Спам и флаги операций; SMTP не сохраняет общую копию в папке Отправленные. Повторяемая ошибка native_access_sync_failed при удалении или изменении разрешения либо преобразовании означает, что сервис намеренно сохранил предыдущее состояние.

Инструменты Sieve (операционный токен)

Инструменты удаления (операционный токен)

Инструменты миграции (операционный токен)

Инструменты тикетов (операционный токен)

Инструменты SMTP и маршрутизации доменов (операционный токен)

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

Приведенные выше инструменты записи и тестирования изменяют настройки или выполняют тест подключения. Администратор локально размещенного stdio может требовать TREKMAIL_ALLOW_DESTRUCTIVE=true, прежде чем они станут доступны; get_domain_smtp, list_domain_smtp_profiles, get_domain_smtp_test_status и get_account_smtp_default работают только для чтения и доступны всегда.

Устаревшие инструменты SMTP

Эти инструменты уровня учетной записи сохранены для обратной совместимости, но больше не управляют маршрутизацией отдельных доменов: используйте вместо них приведенные выше инструменты маршрутизации доменов.

Инструменты метрик спама (операционный токен)

Инструменты учетной записи (операционный токен)

Управление токенами сообщений (операционный токен)

Инструменты сообщений (токен сообщений)

Токен сообщений открывает 62 инструмента, охватывающих всю веб-почту, включая подключенные внешние учетные записи. Инструменты сгруппированы по функциональным областям.

Размещенный OAuth и локальный stdio идентифицируют ящик по-разному. В размещенном HTTP MCP схема каждого инструмента сообщений содержит обязательный mailbox_id; сервер использует его для создания краткосрочного токена этого ящика. В локальном stdio MCP TREKMAIL_MESSAGE_TOKEN уже привязан к одному ящику, поэтому те же инструменты не принимают mailbox_id. Подключенный почтовый ящик является вторым уровнем выбора: передайте external_account_id в дополнение к mailbox_id в размещенном MCP или в дополнение к привязанному токену сообщений в stdio.

Семь из 62 инструментов сообщений управляют подключенными учетными записями, а пять управляют адресами отправителя и политикой ответа. Используйте оба семейства для сценария в стиле Gmail, где агент читает подключенные входящие Gmail, но отправляет с авторизованного рабочего адреса через маршрут домена или сохраненный профиль SMTP. Смотрите Адреса отправки через API и MCP.

Основные операции с сообщениями

Если в настройках почтового ящика в разделе Профиль заданы значения CC по умолчанию или BCC по умолчанию, они добавляются к отправлениям send_message и schedule_message точно так же, как к письмам из веб-приложения; уже присутствующий в сообщении адрес второй раз не добавляется. Передайте apply_default_recipients: false, чтобы не применять настройку к одному сообщению. Она не затрагивает почту, отправленную через SMTP из настольного или мобильного почтового клиента, поскольку такая почта не проходит через API. | report_spam | Сообщить о спаме, переместить сообщение в Спам и обучить фильтр | | report_ham | Отметить сообщение в Спаме как допустимое, переместить во Входящие и обучить фильтр | | bulk_action | Применить действие (прочитать, отметить, удалить, переместить, спам) к 50 сообщениям одновременно |

Папки

Вложения

Черновики

Оба инструмента возвращают uid и uidvalidity черновика. Храните эту пару вместе: update_draft требует эпоху, чтобы старый повторно использованный UID не смог удалить другое сообщение после повторного создания папки Черновики. Черновик, найденный через list_messages, сначала следует открыть с помощью read_message, который возвращает его текущий uidvalidity. Обновление возвращает новую пару, после чего старый UID перестает работать. На сервере без UIDPLUS оба значения могут быть null, даже если новый черновик сохранен; обновите папку Черновики и откройте черновик перед изменением.

Оба инструмента также принимают необязательный idempotency_key. Если не указывать его, каждый вызов считается новым, поэтому двукратное сохранение одного черновика создаст два черновика. При повторе вызова, который мог уже завершиться, передавайте тот же ключ, чтобы получить первый результат вместо дубликата.

Запланированная отправка

Контакты

Группы контактов

Календарь

Помощники составления сообщений

Эти инструменты подготавливают данные для ответа или пересылки. Они ничего не отправляют. Передайте возвращенные данные непосредственно в send_message или save_draft.

Идентификаторы отправителя (адреса отправки)

Шаблоны

Заблокированные отправители

Инструменты проверки email (операционный токен)

Инструменты проверки email доступны на всех тарифах, включая Nano. Единственное ограничение связано с остатком кредитов.

Инструменты Cloudflare (операционный токен)

Инструменты Cloudflare доступны на тарифах Pro и Agency.

Средства безопасности самостоятельно размещенного stdio

Когда вы самостоятельно запускаете сервер MCP stdio, параметр TREKMAIL_ALLOW_DESTRUCTIVE определяет, разрешает ли локальный процесс удаление и другие операции записи. Устанавливайте значение true, только если доверяете агенту удаление почтовых ящиков. Эта настройка не влияет на доступность функций в размещенном TrekMail.

Даже при включенных разрушительных операциях удаление всегда выполняется в два этапа, и агент должен явно задать confirm: true. Подробности приведены в статье Защитные механизмы и намерения удаления.

Защитные разрешения отправки

Инструменты send_message и schedule_message имеют два независимых защитных разрешения, которые должны выполняться одновременно:

1. Разрешение окружения: при запуске сервера MCP должно быть задано TREKMAIL_ALLOW_SENDING=true.
2. Разрешение для вызова: при каждом вызове агент должен передавать параметр confirm_send=true.

Двойное разрешение предотвращает случайную отправку email самостоятельно размещенным процессом. Задайте TREKMAIL_ALLOW_SENDING=false, если агент должен только читать сообщения. list_scheduled работает без этого средства управления; оно применяется только к созданию или отправке запланированных сообщений.

Защитные разрешения миграции

Инструменты записи миграции (start_migration, retry_migration, delete_migration, delete_bulk_migration, update_bulk_migration_job_password, test_migration_connection, preview_bulk_migration, start_bulk_migration, retry_bulk_migration) имеют два независимых защитных разрешения:

1. Разрешение окружения: при запуске сервера MCP должно быть задано TREKMAIL_ALLOW_MIGRATION=true.
2. Разрешение для вызова: каждому инструменту требуется собственный параметр подтверждения (confirm_start=true, confirm_retry=true или confirm_delete=true).

cancel_migration, cancel_bulk_migration и resume_bulk_migration всегда доступны независимо от настройки окружения для самостоятельного размещения, поскольку это операции безопасности или возобновления. Для них по-прежнему требуются параметры подтверждения при вызове.

Инструменты миграции только для чтения (list_migrations, get_migration, list_bulk_migrations, get_bulk_migration) работают без защитных разрешений.

Быстрые решения

• Агент не может подключиться: убедитесь, что путь build/index.js указан правильно и после клонирования выполнена команда npm run build.
• Ошибки "Missing bearer token": убедитесь, что задан хотя бы один из параметров TREKMAIL_API_TOKEN и TREKMAIL_MESSAGE_TOKEN.
• Инструменты чтения работают, а запись завершается ошибкой: токен относится к тарифу Starter. Запись в Drive работает на Starter с полным набором функций Drive. Для других операций записи, создания ящиков, запуска миграций и ответов на тикеты перейдите на Pro или используйте панель.
• Инструменты удаления возвращают ошибки в самостоятельно размещенном stdio: задайте TREKMAIL_ALLOW_DESTRUCTIVE=true в окружении этого процесса MCP. Настройка относится к удалению и другим операциям записи, включая сообщения, папки, контакты, календарь, идентификаторы, шаблоны, заблокированных отправителей и запланированные сообщения.
• Инструмент отправки в самостоятельно размещенном stdio возвращает "Sending is disabled": задайте TREKMAIL_ALLOW_SENDING=true в окружении этого процесса MCP.
• Инструмент отправки возвращает "Send not confirmed": агент должен передавать confirm_send=true при каждом вызове send_message или schedule_message.
• Инструменты сообщений не отображаются: убедитесь, что TREKMAIL_MESSAGE_TOKEN задан с действительным токеном tm_msg_.
• Инструменты записи миграции в самостоятельно размещенном stdio возвращают ошибки: задайте TREKMAIL_ALLOW_MIGRATION=true в окружении этого процесса MCP.
• Ошибка 503 при запуске миграции: сервер достиг предельного количества миграций. Повторите попытку через несколько минут.
• Не удается скачать вложение: вложения возвращаются в Base64. Загрузка больших вложений размером до 25 МБ может занять несколько секунд. download_all_attachments возвращает ZIP со всеми вложениями в кодировке Base64.
• Черновик исчез после обновления: update_draft удаляет старый черновик и добавляет замену, поэтому черновик получает новый идентификатор UID. Для всех последующих операций используйте из ответа и uid, и uidvalidity; переданная пара больше не указывает на замену.
• Копия каждого сообщения приходит на адрес, который вы не указывали: в разделе Настройки → Профиль для ящика установлен CC по умолчанию или BCC по умолчанию. Настройка применяется ко всему, что отправляет этот ящик, в том числе через API. Очистите ее там или передайте apply_default_recipients: false, чтобы не применять к одному сообщению.
• Событие календаря не найдено: события относятся к определенному почтовому ящику. Убедитесь, что токен сообщений выдан для нужного ящика.

Связанные статьи

• Обзор API
• Создание токенов API и управление ими
• Защитные механизмы и намерения удаления