Mailtrap

официальный

Интегрируется с Mailtrap Email API.

GitHub
63

Что можно делать с Mailtrap MCP?

  • Отправка транзакционных писем — Запросите отправку письма через send-email с встроенным содержимым или шаблоном, включая CC/BCC и пользовательские переменные.
  • Управление шаблонами писем — Используйте list-templates, create-template, update-template или delete-template для поддержки переиспользуемых дизайнов писем.
  • Просмотр журналов доставки — Запросите list-email-logs с фильтрами по получателю, статусу или дате, затем детально изучите с помощью get-email-log-message.
  • Тестирование писем в песочнице — Отправьте на тестовый ящик через send-sandbox-email, затем просмотрите сообщения с помощью get-sandbox-messages и show-sandbox-email-message.
  • Анализ эффективности отправки — Получите показатели доставки, отказов и вовлечённости через get-sending-stats, при необходимости с разбивкой по домену или категории.
  • Настройка инфраструктуры отправки — Управляйте list-sending-domains, создавайте или удаляйте домены, получайте инструкции по настройке DNS.

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

TypeScript test NPM

MCP Mailtrap Server

MCP-сервер, предоставляющий инструменты для отправки и тестирования писем в песочнице через Mailtrap.

Предварительные требования

Перед использованием этого MCP-сервера необходимо:

  1. Создать аккаунт Mailtrap
  2. Подтвердить свой домен
  3. Получить API-токен в настройках API Mailtrap
  4. Получить свой Account ID в управлении аккаунтом Mailtrap

Требуемые переменные окружения:

  • MAILTRAP_API_TOKEN — обязательна для всего функционала
  • MAILTRAP_ACCOUNT_ID — обязательна для шаблонов, статистики, журналов писем, просмотра/списка песочницы и доменов отправки. Опциональна только для инструментов отправки (send-email, send-sandbox-email и инструментов batch-send-*).

Опционально (можно передавать как параметры инструмента):

  • DEFAULT_FROM_EMAIL — адрес отправителя по умолчанию, когда from не передан в send-email, send-sandbox-email или инструменты batch-send-* (где он заполняет base.from). Позволяет менять отправителя для каждого вызова через параметр from.
  • MAILTRAP_SANDBOX_ID — ID песочницы по умолчанию для инструментов песочницы, когда sandbox_id не передан. Позволяет переключаться между песочницами для каждого вызова через параметр sandbox_id.
  • MAILTRAP_TEST_INBOX_ID — ID тестового inbox по умолчанию для инструментов песочницы, когда test_inbox_id не передан. Позволяет переключаться между inbox для каждого вызова через параметр test_inbox_id. Устаревший псевдоним для MAILTRAP_SANDBOX_ID, по-прежнему используется как запасной вариант.
  • MAILTRAP_ORGANIZATION_ID — обязательна для инструментов организации (list-sub-accounts, create-sub-account).
  • MAILTRAP_ORGANIZATION_API_TOKEN — API-токен уровня организации. Обязателен для инструментов организации (отдельно от MAILTRAP_API_TOKEN).

Быстрая установка

Install in Cursor

Install with Node in VS Code

Smithery CLI

Smithery — это установщик реестра и менеджер MCP-серверов, работающий со всеми AI-клиентами.

npx @smithery/cli install mailtrap

Smithery автоматически обрабатывает конфигурацию клиента и предоставляет интерактивный процесс настройки. Это самый простой способ начать работу с MCP-серверами локально.

Настройка

Claude Desktop

Используйте MCPB для установки сервера Mailtrap. Эти файлы можно найти в разделе Releases.
Скачайте файл .MCPB и откройте его. Если у вас установлен Claude Desktop — он откроет файл и предложит настроить.

Claude Desktop или Cursor

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

{
  "mcpServers": {
    "mailtrap": {
      "command": "npx",
      "args": ["-y", "mcp-mailtrap"],
      "env": {
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

Если вы используете asdf для управления Node.js, необходимо указать абсолютный путь к исполняемому файлу (пример для Mac):

{
  "mcpServers": {
    "mailtrap": {
      "command": "/Users/<username>/.asdf/shims/npx",
      "args": ["-y", "mcp-mailtrap"],
      "env": {
        "PATH": "/Users/<username>/.asdf/shims:/usr/bin:/bin",
        "ASDF_DIR": "/opt/homebrew/opt/asdf/libexec",
        "ASDF_DATA_DIR": "/Users/<username>/.asdf",
        "ASDF_NODEJS_VERSION": "20.6.1",
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

Расположение файла конфигурации Claude Desktop

Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Расположение файла конфигурации Cursor

Mac: ~/.cursor/mcp.json

Windows: %USERPROFILE%\.cursor\mcp.json

VS Code

Ручное изменение конфигурации

Выполните в палитре команд: Preferences: Open User Settings (JSON)

Затем добавьте в файл настроек следующую конфигурацию:

{
  "mcp": {
    "servers": {
      "mailtrap": {
        "command": "npx",
        "args": ["-y", "mcp-mailtrap"],
        "env": {
          "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
          "DEFAULT_FROM_EMAIL": "your_sender@example.com",
          "MAILTRAP_ACCOUNT_ID": "your_account_id",
          "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
        }
      }
    }
  }
}

[!TIP] Не забудьте перезапустить MCP-сервер после изменения раздела "env".

MCP Bundle (MCPB)

Для простой установки в хостах, поддерживающих MCP Bundles, можно распространять файл пакета .mcpb.

# Build TypeScript and pack the MCPB bundle
npm run mcpb:pack

# Inspect bundle metadata
npm run mcpb:info

# Sign the bundle for distribution (optional)
npm run mcpb:sign

Это создаёт mailtrap-mcp.mcpb с использованием репозитория manifest.json и собранных артефактов в dist/.

Использование

После настройки вы можете попросить агента отправлять письма и управлять шаблонами, например:

Операции отправки писем:

  • «Отправь письмо на john.doe@example.com с темой "Встреча завтра" и дружеским напоминанием о предстоящей встрече.»
  • «Отправь письмо sarah@example.com об обновлении проекта и скопируй команду team@example.com»
  • «Отправь приветственный шаблон (uuid b81aabcd-1a1e-41cf-91b6-eca0254b3d96) на new@example.com с переменными { name: 'Alex' }»
  • «Отправь письмо в песочницу на test@example.com с темой "Тестовый шаблон", чтобы посмотреть, как выглядит наше приветственное письмо»

Журналы писем (отладка доставки):

  • «Покажи мои последние журналы отправленных писем»
  • «Покажи журналы писем, отправленных на user@example.com»
  • «Получи сообщение журнала письма для ID abc-123-uuid, чтобы проверить статус доставки»

Статистика отправки:

  • «Получи статистику отправки за январь 2025»
  • «Покажи процент доставки в разрезе доменов за прошлый месяц»
  • «Какая у меня статистика писем по категориям с 2025-01-01 по 2025-01-31?»

Операции с песочницей:

  • «Получи все сообщения из моего inbox в песочнице»
  • «Покажи первую страницу сообщений песочницы»
  • «Найди сообщения, содержащие "test", в моём inbox песочницы»
  • «Покажи детали сообщения песочницы с ID 5159037506»

Операции с шаблонами:

  • «Перечисли все шаблоны писем в моём аккаунте Mailtrap»
  • «Создай новый шаблон письма под названием "Приветственное письмо" с темой "Добро пожаловать на нашу платформу!"»
  • «Обнови шаблон с ID 12345, изменив тему на "Обновлённое приветственное сообщение"»
  • «Удали шаблон с ID 67890»

Домены отправки:

  • «Перечисли мои домены отправки»
  • «Получи домен отправки с ID 3938»
  • «Создай домен отправки для example.com»
  • «Удали домен отправки 3938»
  • «Получи домен отправки 3938 с инструкциями по настройке DNS»

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

send-email

Отправляет транзакционное письмо через Mailtrap. Поддерживает два взаимоисключающих режима — встроенное содержимое (subject + text/html) или на основе шаблона (template_uuid).

Параметры:

  • from (опционально): Отправитель в формате { email, name? } (строка с email-адресом также принимается во время выполнения). Если не указан, используется DEFAULT_FROM_EMAIL.
  • to (опционально): Массив получателей в виде объектов { email, name? } (строки с email-адресами или одиночный не-массивный адрес также принимаются во время выполнения). Опционален, если указан cc или bcc; как минимум один из to / cc / bcc должен содержать получателя.
  • cc (опционально): Массив получателей копии (CC) в виде объектов { email, name? } (строки с email-адресами также принимаются во время выполнения).
  • bcc (опционально): Массив получателей скрытой копии (BCC) в виде объектов { email, name? } (строки с email-адресами также принимаются во время выполнения).
  • subject (условно): Тема письма. Обязательна для встроенных отправок; должна быть опущена, когда задан template_uuid.
  • text (условно): Текстовое содержимое письма. Обязательно (наряду с html или вместо него) для встроенных отправок; должно быть опущено, когда задан template_uuid.
  • html (условно): HTML-версия содержимого письма. Обязательна (наряду с text или вместо него) для встроенных отправок; должна быть опущена, когда задан template_uuid.
  • category (опционально): Категория письма для отслеживания и аналитики. Должна быть опущена, когда задан template_uuid.
  • template_uuid (опционально): Использовать шаблон Mailtrap вместо встроенного содержимого. При задании subject / text / html / category должны быть опущены (по API Mailtrap).
  • template_variables (опционально): Объект переменных, подставляемых в шаблон, на который ссылается template_uuid. Разрешён только вместе с template_uuid.

batch-send-transactional-email

Отправляет пакет транзакционных писем одним вызовом API Mailtrap (поток отправки по умолчанию). Общие поля задаются в base; переопределения для каждого получателя — в requests[]. Каждый запрос должен содержать как минимум одного получателя через to, cc или bcc. Действуют те же правила взаимоисключения встроенного содержимого и шаблона, что и для send-email — проверяются после объединения базовых полей с каждым запросом.

Параметры:

  • base (опционально): Объект с полями, общими для всего пакета.
    • from (опционально): Отправитель в формате { email, name? } (строка с email-адресом также принимается во время выполнения). Откат к DEFAULT_FROM_EMAIL.
    • reply_to (опционально): Адрес для ответа (reply-to).
    • subject / text / html / category (опционально, встроенный режим): Содержимое по умолчанию для каждого запроса.
    • template_uuid / template_variables (опционально, режим шаблона): Шаблон и переменные по умолчанию. Взаимоисключающие со встроенными полями.
    • custom_variables (опционально): Пользовательские переменные по умолчанию (строковые значения).
    • headers (опционально): Пользовательские заголовки по умолчанию.
  • requests (обязательно): Непустой массив сообщений для каждого получателя. Каждая запись содержит:
    • to (опционально): Массив получателей в виде объектов { email, name? } (строки с email-адресами или одиночный не-массивный адрес также принимаются во время выполнения). Опционален, если указан cc или bcc; как минимум один из to / cc / bcc должен содержать получателя.
    • cc, bcc, reply_to (опционально).
    • Переопределения встроенного содержимого (subject/text/html/category) или шаблона (template_uuid/template_variables); любое опущенное поле откатывается к соответствующему значению из base.
    • custom_variables, headers (опционально).

batch-send-bulk-email

Отправляет пакет массовых писем через bulk-stream API Mailtrap. Та же структура base + requests[], те же правила валидации и взаимоисключения встроенного содержимого и шаблона, что и для batch-send-transactional-email — единственное отличие в том, что этот инструмент направляет вызов через bulk-эндпоинт вместо транзакционного. См. параметры выше.

list-email-logs

Выводит список журналов отправленных писем (история доставки) с опциональной пагинацией и фильтрами. Используйте для отладки проблем с доставкой прямо из IDE.

Параметры:

  • search_after (опционально): Курсор пагинации из поля next_page_cursor предыдущего ответа
  • sent_after (опционально): Дата/время в формате ISO 8601; только журналы, отправленные после этого времени
  • sent_before (опционально): Дата/время в формате ISO 8601; только журналы, отправленные до этого времени
  • from_email (опционально): Фильтр по email отправителя; используется с from_operator (по умолчанию: ci_equal)
  • to_email (опционально): Фильтр по email получателя; используется с to_operator (по умолчанию: ci_equal)
  • status (опционально): Фильтр по статусу доставки: delivered, not_delivered, enqueued, opted_out; используется с status_operator (по умолчанию: equal)
  • subject (опционально): Фильтр по теме письма; используется с subject_operator (по умолчанию: ci_contain). Используйте subject_operator: empty/not_empty для фильтрации по наличию темы.
  • sending_domain_id (опционально): Фильтр по ID домена отправки (число); используется с sending_domain_id_operator (по умолчанию: equal)
  • sending_stream (опционально): Фильтр по потоку: transactional или bulk; используется с sending_stream_operator (по умолчанию: equal)
  • events (опционально): Фильтр по типу(ам) события: delivery, open, click, bounce, spam, unsubscribe, soft_bounce, reject, suspension; используется с events_operator (include_event / not_include_event)
  • clicks_count / opens_count (опционально): Фильтр по количеству кликов/открытий; используется с *_operator: equal, greater_than, less_than
  • client_ip / sending_ip (опционально): Фильтр по IP; используется с *_operator: equal, not_equal, contain, not_contain
  • email_service_provider_response (опционально): Фильтр по тексту ответа провайдера; используется с *_operator (ci_contain и т.д.)
  • email_service_provider (опционально): Фильтр по провайдеру (точное совпадение); используется с *_operator: equal, not_equal
  • recipient_mx (опционально): Фильтр по MX получателя; используется с recipient_mx_operator (ci_contain и т.д.)
  • category (опционально): Фильтр по категории письма; используется с category_operator: equal, not_equal

Все параметры опциональны.

get-email-log-message

Получает одно сообщение журнала письма по ID (UUID): читаемое резюме (от, кому, тема, время отправки, статус, категория, поток, вовлечённость, контекст доставки), затем подробную историю событий. Опционально, с помощью include_content: true, можно также загрузить и показать содержимое письма (HTML и обычный текст), когда Mailtrap предоставляет URL исходного сообщения.

Параметры:

  • message_id (обязательно): UUID сообщения в журнале электронной почты (из ответа об отправке или списка журналов писем). Используйте list-email-logs, чтобы найти идентификаторы сообщений.
  • include_content (необязательно): если указано true, загружает исходное сообщение в формате EML (если доступен raw_message_url) и добавляет разобранные секции HTML и обычного текста, аналогично show-sandbox-email-message.

get-sending-stats

Получение статистики отправки писем (показатели доставки, отказов, открытий, переходов по ссылкам, спама) за указанный диапазон дат. При необходимости — разбивка по доменам, категориям, почтовым провайдерам или датам. Проверяйте показатели доставки, не покидая редактор.

Параметры:

  • start_date (обязательно): начальная дата диапазона статистики (ГГГГ-ММ-ДД)
  • end_date (обязательно): конечная дата диапазона статистики (ГГГГ-ММ-ДД)
  • breakdown (необязательно): способ разбивки статистики: aggregated (по умолчанию), by_domain, by_category, by_email_service_provider или by_date
  • sending_domain_ids (необязательно): ограничить результаты указанными идентификаторами доменов отправки (массив целых чисел)
  • sending_streams (необязательно): ограничить по transactional и/или bulk (массив строк)
  • categories (необязательно): ограничить указанными категориями писем (массив строк)
  • email_service_providers (необязательно): ограничить указанными провайдерами, например Google, Yahoo, Outlook (массив строк)

create-template

Создаёт новый шаблон письма в вашем аккаунте Mailtrap.

Параметры:

  • name (обязательно): название шаблона
  • subject (обязательно): тема письма
  • html (или text обязательно): HTML-содержимое шаблона
  • text (или html обязательно): версия шаблона в виде обычного текста
  • category (необязательно): категория шаблона (по умолчанию «General»)

list-templates

Выводит список всех шаблонов писем в вашем аккаунте Mailtrap.

Параметры:

  • Параметры не требуются

get-template

Получение одного шаблона письма по идентификатору, включая тему, категорию и HTML/текстовое содержимое.

Параметры:

  • template_id (обязательно): идентификатор шаблона для получения

update-template

Обновляет существующий шаблон письма.

Параметры:

  • template_id (обязательно): идентификатор шаблона для обновления
  • name (необязательно): новое название шаблона
  • subject (необязательно): новая тема письма
  • html (необязательно): новое HTML-содержимое шаблона
  • text (необязательно): новая версия шаблона в виде обычного текста
  • category (необязательно): новая категория шаблона

[!NOTE] При вызове update-template необходимо указать хотя бы одно обновляемое поле (name, subject, html, text или category), чтобы выполнить обновление.

delete-template

Удаляет существующий шаблон письма.

Параметры:

  • template_id (обязательно): идентификатор шаблона для удаления

send-sandbox-email

Отправляет письмо в ваш тестовый почтовый ящик Mailtrap для целей разработки и тестирования. Это идеально подходит для проверки шаблонов писем без отправки реальным получателям. Поддерживает те же два режима, что и send-email — встроенное содержимое или на основе шаблона (template_uuid).

Параметры:

  • test_inbox_id (необязательно): идентификатор тестового почтового ящика Mailtrap. Обязателен, если не задан MAILTRAP_TEST_INBOX_ID; передавайте при каждом вызове, чтобы указать конкретный ящик.
  • from (необязательно): отправитель в виде { email, name? } (простая строка с email также принимается во время выполнения). Если не указан, используется DEFAULT_FROM_EMAIL.
  • to (необязательно): массив получателей в виде объектов { email, name? } (простые строки с email в массиве или строка с email, разделёнными запятыми, также принимаются во время выполнения). Необязательно, если указаны cc или bcc; как минимум один из to / cc / bcc должен содержать получателя.
  • cc (необязательно): массив получателей копии (CC) в виде объектов { email, name? } (простые строки с email также принимаются во время выполнения).
  • bcc (необязательно): массив получателей скрытой копии (BCC) в виде объектов { email, name? } (простые строки с email также принимаются во время выполнения).
  • subject (условно): тема письма. Обязательна для встроенной отправки; должна быть опущена, если задан template_uuid.
  • text (условно): текст письма. Обязателен (вместе с html или вместо него) для встроенной отправки; должен быть опущен, если задан template_uuid.
  • html (условно): HTML-версия тела письма. Обязательна (вместе с text или вместо него) для встроенной отправки; должна быть опущена, если задан template_uuid.
  • category (необязательно): категория письма для отслеживания. Должна быть опущена, если задан template_uuid.
  • template_uuid (необязательно): использовать шаблон письма Mailtrap вместо встроенного содержимого. Если задан, subject / text / html / category должны быть опущены.
  • template_variables (необязательно): объект переменных, подставляемых в шаблон, на который ссылается template_uuid. Допускается только вместе с template_uuid.

batch-send-sandbox-email

Отправляет пакет писем в ваш тестовый почтовый ящик Mailtrap одним вызовом API, без доставки реальным получателям. Та же структура base + requests[], те же правила проверки и правила «встроенный контент или шаблон», что и в batch-send-transactional-email — отличие в том, что этот инструмент направляет вызов через sandbox-эндпоинт для одного тестового ящика.

Параметры:

  • sandbox_id (необязательно): идентификатор sandbox (тестового почтового ящика) Mailtrap. Обязателен, если не задан MAILTRAP_SANDBOX_ID; передавайте при каждом вызове, чтобы указать конкретный sandbox.
  • base (необязательно), requests (обязательно): см. batch-send-transactional-email выше.

[!NOTE] Для sandbox-инструментов укажите test_inbox_id в вызове инструмента или задайте переменную окружения MAILTRAP_TEST_INBOX_ID. Вы можете переключаться между ящиками при каждом вызове, передавая test_inbox_id. Инструменты, принимающие sandbox_id, сначала используют MAILTRAP_SANDBOX_ID.

get-sandbox-messages

Получает список сообщений из вашего тестового почтового ящика Mailtrap. Полезно для проверки того, какие письма были получены в вашем sandbox во время тестирования.

Параметры:

  • page (необязательно): номер страницы для постраничной навигации (минимум: 1)
  • last_id (необязательно): постраничная навигация по идентификатору последнего сообщения. Возвращает сообщения после указанного идентификатора (минимум: 1)
  • search (необязательно): поисковый запрос для фильтрации сообщений

[!NOTE] Все параметры необязательны. Если ни один не указан, будет возвращена первая страница сообщений из ящика. Используйте page для традиционной постраничной навигации, last_id для навигации на основе курсора или search для фильтрации сообщений по содержимому.

show-sandbox-email-message

Показывает подробную информацию и содержимое конкретного письма из вашего тестового почтового ящика Mailtrap, включая HTML и текстовое содержимое.

Параметры:

  • message_id (обязательно): идентификатор сообщения sandbox для получения

[!NOTE] Сначала используйте get-sandbox-messages, чтобы получить список сообщений и их идентификаторы, затем используйте этот инструмент для просмотра полного содержимого конкретного сообщения.

get-sandbox-project

Получение sandbox-проекта по идентификатору, включая его почтовые ящики и количество писем.

Параметры:

  • project_id (обязательно): идентификатор проекта для получения

update-sandbox-project

Переименование существующего sandbox-проекта.

Параметры:

  • project_id (обязательно): идентификатор проекта для обновления
  • name (обязательно): новое название проекта (2–100 символов)

list-sandboxes

Выводит список всех sandbox, доступных для API-токена, во всех проектах.

Параметры:

  • Параметры не требуются

mark-sandbox-as-read

Пометить все сообщения в sandbox как прочитанные.

Параметры:

  • sandbox_id (обязательно): идентификатор sandbox, с которым нужно выполнить действие

reset-sandbox-credentials

Сброс учётных данных SMTP для sandbox. Возвращает новые имя пользователя и пароль.

Параметры:

  • sandbox_id (обязательно): идентификатор sandbox, с которым нужно выполнить действие

enable-sandbox-email-address

Включение адреса приёма писем для sandbox (включает адрес Mailtrap, который доставляет сообщения в sandbox через SMTP).

Параметры:

  • sandbox_id (обязательно): идентификатор sandbox, с которым нужно выполнить действие

reset-sandbox-email-address

Генерация нового адреса приёма писем для sandbox.

Параметры:

  • sandbox_id (обязательно): идентификатор sandbox, с которым нужно выполнить действие

forward-sandbox-message

Пересылка сообщения из sandbox на внешний адрес электронной почты. Учитывается в вашей месячной квоте пересылок.

Параметры:

  • sandbox_id (необязательно): идентификатор sandbox. Если не указан, используется MAILTRAP_SANDBOX_ID.
  • message_id (обязательно): идентификатор сообщения sandbox для пересылки
  • email (обязательно): адрес электронной почты, на который нужно переслать сообщение

update-sandbox-message

Пометить сообщение в sandbox как прочитанное или непрочитанное.

Параметры:

  • sandbox_id (необязательно): идентификатор sandbox. Если не указан, используется MAILTRAP_SANDBOX_ID.
  • message_id (обязательно): идентификатор сообщения sandbox для обновления
  • is_read (обязательно): true помечает как прочитанное, false помечает как непрочитанное

delete-sandbox-message

Удаление одного сообщения из sandbox.

Параметры:

  • sandbox_id (необязательно): идентификатор sandbox. Если не указан, используется MAILTRAP_SANDBOX_ID.
  • message_id (обязательно): идентификатор сообщения sandbox для удаления

get-sandbox-message-spam-score

Получение отчёта SpamAssassin о спаме для сообщения из sandbox (оценка, правила, полный отчёт). Автономная альтернатива include_spam_report: true на show-sandbox-email-message.

Параметры:

  • sandbox_id (необязательно): идентификатор sandbox. Если не указан, используется MAILTRAP_SANDBOX_ID.
  • message_id (обязательно): идентификатор сообщения sandbox

get-sandbox-message-html-analysis

Получение отчёта об анализе HTML для сообщения из sandbox (оценки совместимости с почтовыми клиентами, проблемные элементы). Автономная альтернатива include_html_analysis: true на show-sandbox-email-message.

Параметры:

  • sandbox_id (необязательно): идентификатор sandbox. Если не указан, используется MAILTRAP_SANDBOX_ID.
  • message_id (обязательно): идентификатор сообщения sandbox

get-sandbox-message-headers

Получение разобранных заголовков письма для сообщения из sandbox.

Параметры:

  • sandbox_id (необязательно): идентификатор sandbox. Если не указан, используется MAILTRAP_SANDBOX_ID.
  • message_id (обязательно): идентификатор сообщения sandbox

get-sandbox-message-html

Получение отрендеренного HTML-содержимого сообщения из sandbox.

Параметры:

  • sandbox_id (необязательно): идентификатор sandbox. Если не указан, используется MAILTRAP_SANDBOX_ID.
  • message_id (обязательно): идентификатор сообщения sandbox

get-sandbox-message-text

Получение текстового содержимого сообщения из sandbox в виде обычного текста.

Параметры:

  • sandbox_id (необязательно): идентификатор sandbox. Если не указан, используется MAILTRAP_SANDBOX_ID.
  • message_id (обязательно): идентификатор сообщения sandbox

get-sandbox-message-raw

Получение исходного сообщения в формате MIME (заголовки + тело) для сообщения из sandbox.

Параметры:

  • sandbox_id (необязательно): идентификатор sandbox. Если не указан, используется MAILTRAP_SANDBOX_ID.
  • message_id (обязательно): идентификатор сообщения sandbox

get-sandbox-message-eml

Получение сообщения в виде файла EML (подходит для прикрепления к тикету или импорта в другой почтовый клиент).

Параметры:

  • sandbox_id (необязательно): идентификатор sandbox. Если не указан, используется MAILTRAP_SANDBOX_ID.
  • message_id (обязательно): идентификатор сообщения sandbox

get-sandbox-message-html-source

Получение неотрендеренного HTML-исходника сообщения из sandbox (HTML до любых преобразований на стороне Mailtrap, таких как переписывание CID-ссылок).

Параметры:

  • sandbox_id (необязательно): идентификатор sandbox. Если не указан, используется MAILTRAP_SANDBOX_ID.
  • message_id (обязательно): идентификатор сообщения sandbox

list-sandbox-attachments

Вывод списка всех вложений в сообщении из sandbox (имя файла, тип содержимого, размер, путь для скачивания).

Параметры:

  • sandbox_id (необязательно): идентификатор sandbox. Если не указан, используется MAILTRAP_SANDBOX_ID.
  • message_id (обязательно): идентификатор сообщения sandbox

get-sandbox-attachment

Получение метаданных и URL для скачивания одного вложения.

Параметры:

  • sandbox_id (необязательно): ID песочницы. Если не указан, используется MAILTRAP_SANDBOX_ID.
  • message_id (обязательно): ID сообщения песочницы, содержащего вложение
  • attachment_id (обязательно): ID вложения для получения

list-sending-domains

Список доменов отправителя и статус их DNS-проверки.

Параметры:

  • Параметры не требуются

get-sending-domain

Получение домена отправителя по ID и его статуса проверки (включая DNS-записи). При необходимости можно включить инструкции по настройке DNS, установив include_setup_instructions в значение true.

Параметры:

  • sending_domain_id (обязательно): ID домена отправителя
  • include_setup_instructions (необязательно): Если true, в ответ добавляются инструкции по настройке DNS. По умолчанию: false

create-sending-domain

Создание нового домена отправителя. После создания добавьте DNS-записи для проверки домена (используйте get-sending-domain с параметром include_setup_instructions: true, чтобы увидеть записи).

Параметры:

  • domain_name (обязательно): Имя домена (например, example.com)

delete-sending-domain

Удаление домена отправителя.

Параметры:

  • sending_domain_id (обязательно): ID домена отправителя для удаления

send-sending-domain-setup-instructions

Отправка по электронной почте инструкций по настройке DNS для домена отправителя на указанный адрес. Полезно для передачи DNS-записей коллеге по DevOps.

Параметры:

  • sending_domain_id (обязательно): ID домена отправителя
  • email (обязательно): Адрес электронной почты для отправки инструкций по настройке DNS

list-suppressions

Список или поиск подавлений (жёсткие отказы, жалобы на спам, отписки, ручные импорты). Возвращает до 1000 результатов за вызов.

Параметры:

  • email (необязательно): Фильтр по адресу электронной почты. Возвращает только подавления, соответствующие этому адресу.

delete-suppression

Удаление подавления по ID. Mailtrap возобновит доставку на этот адрес, если он не будет подавлен снова.

Параметры:

  • suppression_id (обязательно): ID подавления для удаления

list-webhooks

Список всех вебхуков, настроенных для аккаунта. Возвращает полные записи вебхуков в формате JSON.

Параметры:

  • Параметры не требуются

get-webhook

Получение одного вебхука по ID. Возвращает полную запись вебхука в формате JSON. Примечание: signing_secret не возвращается здесь — он доступен только в ответе от create-webhook.

Параметры:

  • webhook_id (обязательно): ID вебхука для получения

create-webhook

Создание вебхука. Ответ включает signing_secret для проверки подписей полезной нагрузки вебхука — этот секрет возвращается только при создании, поэтому сохраните его сейчас. Если вы его потеряете, пересоздайте вебхук.

Параметры:

  • url (обязательно): URL, на который Mailtrap будет отправлять события вебхука методом POST
  • webhook_type (обязательно): "email_sending", "audit_log" или "inbound_receiving"
  • active (необязательно, логический): по умолчанию true
  • payload_format (необязательно): "json" или "jsonlines". По умолчанию "json"
  • sending_stream (необязательно, только email_sending): "transactional" или "bulk"
  • event_types (необязательно, только email_sending): массив из delivery, soft_bounce, bounce, suspension, unsubscribe, open, spam_complaint, click, reject
  • domain_id (необязательно, только email_sending): ID домена отправителя для ограничения области действия этого вебхука
  • inbound_inbox_id (необязательно, только inbound_receiving): ID входящего почтового ящика, с которым связан вебхук; не указывайте, чтобы применить ко всем почтовым ящикам в аккаунте

update-webhook

Обновление изменяемых полей вебхука. webhook_type, sending_stream и domain_id нельзя изменить после создания — пересоздайте вебхук, если вам нужно их изменить.

Параметры:

  • webhook_id (обязательно): ID вебхука для обновления
  • url (необязательно): Новый URL вебхука
  • active (необязательно, логический): Включить или отключить вебхук
  • payload_format (необязательно): "json" или "jsonlines"
  • event_types (необязательно, только email_sending): массив из delivery, soft_bounce, bounce, suspension, unsubscribe, open, spam_complaint, click, reject
  • inbound_inbox_id (необязательно, только inbound_receiving): ID входящего почтового ящика, с которым связан вебхук

delete-webhook

Окончательное удаление вебхука по ID. Возвращает запись удалённого вебхука.

Параметры:

  • webhook_id (обязательно): ID вебхука для удаления

get-contact

Получение контакта по ID или адресу электронной почты. Возвращает полную запись контакта (членство в списках, статус, пользовательские поля).

Параметры:

  • contact_identifier (обязательно): ID контакта или адрес электронной почты

create-contact

Создание нового контакта.

Параметры:

  • email (обязательно): Адрес электронной почты
  • fields (необязательно): Значения пользовательских полей, ключ — merge-тег (например, first_name). Строковые, числовые или логические значения
  • list_ids (необязательно): ID списков контактов для подписки этого контакта
  • unsubscribed (необязательно, логический): Создать контакт со статусом unsubscribed

update-contact

Обновление существующего контакта по ID или адресу электронной почты. list_ids заменяет полный набор членств контакта; list_ids_included/list_ids_excluded добавляют/удаляют, не затрагивая остальное.

Параметры:

  • contact_identifier (обязательно): ID контакта или адрес электронной почты
  • email (необязательно): Новый адрес электронной почты
  • fields (необязательно): Значения пользовательских полей, ключ — merge-тег
  • list_ids (необязательно): Заменить набор членств на этот точный список
  • list_ids_included (необязательно): ID списков для добавления (аддитивно)
  • list_ids_excluded (необязательно): ID списков для удаления
  • unsubscribed (необязательно, логический): Установите unsubscribed (true) или subscribed (false)

delete-contact

Окончательное удаление контакта по ID или адресу электронной почты. Возвращает запись удалённого контакта, если API отвечает с ней; в противном случае возвращает подтверждающую полезную нагрузку.

Параметры:

  • contact_identifier (обязательно): ID контакта или адрес электронной почты

create-contact-event

Запись события контакта для контакта (по ID или адресу электронной почты). Используется для запуска автоматизаций на основе списков контактов.

Параметры:

  • contact_identifier (обязательно): ID контакта или адрес электронной почты
  • name (обязательно): Имя события (соответствует триггерам автоматизации)
  • params (обязательно): Объект произвольных пар ключ/значение. Значения могут быть строкой, числом, логическим значением или null

list-contact-lists

Список всех списков контактов для аккаунта.

Параметры:

  • search (необязательно): Фильтр списков контактов по имени (без учёта регистра), например news

get-contact-list

Получение списка контактов по ID.

Параметры:

  • list_id (обязательно): ID списка контактов для получения

create-contact-list

Создание нового списка контактов.

Параметры:

  • name (обязательно): Имя для нового списка

update-contact-list

Переименование существующего списка контактов.

Параметры:

  • list_id (обязательно): ID списка контактов
  • name (обязательно): Новое имя для списка

delete-contact-list

Окончательное удаление списка контактов по ID.

Параметры:

  • list_id (обязательно): ID списка контактов для удаления

list-contact-fields

Список всех определений полей контактов для аккаунта.

Параметры:

  • Параметры не требуются

get-contact-field

Получение определения поля контакта по ID.

Параметры:

  • field_id (обязательно): ID поля контакта

create-contact-field

Создание нового определения поля контакта. merge_tag должен быть уникальным в пределах аккаунта и используется как имя плейсхолдера в переменных шаблона.

Параметры:

  • name (обязательно): Отображаемое имя (например, «First Name»)
  • merge_tag (обязательно): Уникальное имя плейсхолдера (например, first_name)
  • data_type (обязательно): Одно из text, number, boolean, date

update-contact-field

Обновление определения поля контакта. Можно изменить любую комбинацию name, merge_tag и data_type.

Параметры:

  • field_id (обязательно): ID поля контакта
  • name (необязательно): Новое отображаемое имя
  • merge_tag (необязательно): Новый merge-тег (должен оставаться уникальным)
  • data_type (необязательно): Одно из text, number, boolean, date

delete-contact-field

Окончательное удаление определения поля контакта по ID.

Параметры:

  • field_id (обязательно): ID поля контакта для удаления

create-contact-import

Массовый импорт контактов. Возвращает запись задания импорта; проверяйте его статус с помощью get-contact-import.

Параметры:

  • contacts (обязательно): Массив записей контактов. Каждая запись должна содержать:
    • email (обязательно): Адрес электронной почты контакта
    • fields (необязательно): Значения пользовательских полей, ключ — merge-тег (строковые или числовые значения)
    • list_ids_included (необязательно): ID списков для добавления контакта
    • list_ids_excluded (необязательно): ID списков для удаления контакта

get-contact-import

Получение статуса задания импорта контактов (created/started/finished/failed) со счётчиками created/updated/over-limit.

Параметры:

  • import_id (обязательно): ID задания импорта контактов

create-contact-export

Экспорт контактов, соответствующих набору фильтров, объединённых по И (AND). Возвращает запись задания экспорта; проверяйте статус с помощью get-contact-export, чтобы получить URL для скачивания, когда status станет finished.

Параметры:

  • filters (обязательно): Массив объектов фильтров. Каждый содержит:
    • name (обязательно): Поле для фильтрации (list_id, subscription_status, email и т. д.)
    • operator (обязательно): Одно из equal, not_equal, contains, not_contains, is_empty, is_not_empty
    • value (обязательно): Значение для сравнения (строка, число, логическое значение или массив)

get-contact-export

Получение статуса задания экспорта контактов. Когда status станет finished, поле url будет содержать ссылку для скачивания CSV.

Параметры:

  • export_id (обязательно): ID задания экспорта контактов

list-accounts

Список аккаунтов Mailtrap, к которым имеет доступ текущий API-токен, с уровнями доступа для каждого аккаунта.

Параметры:

  • Параметры не требуются

get-billing-usage

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

Параметры:

  • Параметры не требуются

list-account-accesses

Список доступов к аккаунту (пользователи, приглашения, API-токены). Необязательные фильтры сужают результат до конкретных ресурсов. Требуются права администратора/владельца аккаунта.

Параметры:

  • domain_uuids (необязательно): Фильтр по UUID доменов отправителя (массив строк)
  • inbox_ids (необязательно): Фильтр по ID входящих почтовых ящиков песочницы (массив строк)
  • project_ids (необязательно): Фильтр по ID проектов песочницы (массив строк)

remove-account-access

Удаление доступа к аккаунту по ID. Для спецификаторов User это отзывает их разрешения; для спецификаторов Invite или ApiToken это полностью удаляет спецификатор. Требуются права администратора/владельца.

Параметры:

  • account_access_id (обязательно): ID записи доступа для удаления

get-permission-resources

Получение всех ресурсов (почтовые ящики, проекты, домены, биллинг, аккаунт), к которым API-токен имеет административный доступ, с вложенностью по иерархии.

Параметры:

  • Параметры не требуются

bulk-update-permissions

Массовое создание, обновление или удаление разрешений для одного доступа к аккаунту. Существующие пары (resource_type, resource_id) обновляются; новые создаются. Установите destroy: true в записи, чтобы удалить её.

Параметры:

  • account_access_id (обязательно): ID доступа целевого аккаунта
  • permissions (обязательно): Массив записей разрешений. Каждая запись содержит:
    • resource_id (обязательно): ID ресурса (число или строка)
    • resource_type (обязательно): Одно из: account, project, inbox, domain, billing
    • access_level (необязательно): admin/100 или viewer/10
    • destroy (необязательно, boolean): Если true, удаляет это разрешение вместо создания/обновления

list-api-tokens

Выводит список всех API-токенов аккаунта.

Параметры:

  • Параметры не требуются

create-api-token

Создаёт новый API-токен. Ответ содержит секретное значение token — это единственный момент, когда возвращается полный токен, поэтому сохраните его сразу. Если вы его потеряете, токен придётся пересоздать.

Параметры:

  • name (обязательно): Отображаемое имя токена
  • resources (необязательно): Массив разрешений на ресурсы для ограничения области действия токена. Каждая запись содержит:
    • resource_type (обязательно): Одно из: account, project, inbox, domain, billing
    • resource_id (обязательно): ID ресурса
    • access_level (обязательно): 100 (администратор) или 10 (наблюдатель)

get-api-token

Получает API-токен по ID. Возвращает только метаданные — секретное значение токена здесь не возвращается (только из create-api-token / reset-api-token).

Параметры:

  • api_token_id (обязательно): ID API-токена

reset-api-token

Сбрасывает (ротирует) API-токен по ID. Ответ содержит новое секретное значение token — оно возвращается только при этом вызове, поэтому сохраните его сразу. Предыдущий токен становится недействительным.

Параметры:

  • api_token_id (обязательно): ID API-токена для сброса

delete-api-token

Безвозвратно удаляет API-токен по ID. После удаления токен больше не может использоваться для аутентификации.

Параметры:

  • api_token_id (обязательно): ID API-токена для удаления

list-sub-accounts

Выводит список субаккаунтов в организации. Требует переменную окружения MAILTRAP_ORGANIZATION_ID и права управления субаккаунтами.

Параметры:

  • Параметры не требуются

create-sub-account

Создаёт новый субаккаунт в организации. Требует переменную окружения MAILTRAP_ORGANIZATION_ID и права управления субаккаунтами.

Параметры:

  • name (обязательно): Отображаемое имя нового субаккаунта

list-inbound-folders

Выводит список всех входящих папок в аккаунте. Возвращает форматированную сводку.

Параметры:

  • Параметры не требуются

get-inbound-folder

Получает одну входящую папку по ID. Возвращает полную запись папки в формате JSON.

Параметры:

  • folder_id (обязательно): ID входящей папки

create-inbound-folder

Создаёт новую входящую папку.

Параметры:

  • name (обязательно): Имя папки

update-inbound-folder

Переименовывает входящую папку.

Параметры:

  • folder_id (обязательно): ID входящей папки
  • name (обязательно): Новое имя папки

delete-inbound-folder

Безвозвратно удаляет входящую папку вместе со всеми её почтовыми ящиками.

Параметры:

  • folder_id (обязательно): ID входящей папки

list-inbound-inboxes

Выводит список всех почтовых ящиков во входящей папке. Возвращает форматированную сводку.

Параметры:

  • folder_id (обязательно): ID входящей папки

get-inbound-inbox

Получает один входящий почтовый ящик по ID. Возвращает полную запись почтового ящика в формате JSON.

Параметры:

  • folder_id (обязательно): ID входящей папки
  • inbox_id (обязательно): ID почтового ящика

create-inbound-inbox

Создаёт новый входящий почтовый ящик в папке.

Параметры:

  • folder_id (обязательно): ID входящей папки
  • name (обязательно): Имя почтового ящика
  • domain_id (необязательно): Привязать к пользовательскому домену отправки (catch-all почтовый ящик). Опустите для почтового ящика, размещённого на Mailtrap

update-inbound-inbox

Переименовывает входящий почтовый ящик.

Параметры:

  • folder_id (обязательно): ID входящей папки
  • inbox_id (обязательно): ID почтового ящика
  • name (обязательно): Новое имя почтового ящика

delete-inbound-inbox

Безвозвратно удаляет входящий почтовый ящик.

Параметры:

  • folder_id (обязательно): ID входящей папки
  • inbox_id (обязательно): ID почтового ящика

list-inbound-messages

Выводит список полученных сообщений во входящем почтовом ящике (постранично через курсор). Возвращает форматированную сводку с подсказкой о следующей странице, если есть ещё результаты.

Параметры:

  • inbox_id (обязательно): ID почтового ящика
  • last_id (необязательно): Курсор пагинации из поля last_id предыдущего ответа

get-inbound-message

Получает одно входящее сообщение с полным телом и URL для скачивания вложений. Возвращает полную запись сообщения в формате JSON.

Параметры:

  • inbox_id (обязательно): ID почтового ящика
  • message_id (обязательно): ID сообщения

delete-inbound-message

Безвозвратно удаляет входящее сообщение.

Параметры:

  • inbox_id (обязательно): ID почтового ящика
  • message_id (обязательно): ID сообщения

reply-to-inbound-message

Отвечает на входящее сообщение (отправка исходному отправителю). Отправляет реальное письмо. Адреса принимают строку с email или { email, name? }.

Параметры:

  • inbox_id (обязательно): ID почтового ящика
  • message_id (обязательно): ID сообщения, на которое нужно ответить
  • text / html (рекомендуется хотя бы одно): Текст ответа
  • from (необязательно): Отправитель. Отклоняется для почтовых ящиков, размещённых на Mailtrap; обязателен для почтовых ящиков на пользовательском домене
  • cc / bcc / reply_to (необязательно): Дополнительные адреса
  • category (необязательно): Категория сообщения
  • attachments (необязательно): Массив { content (base64), filename, type?, disposition?, content_id? }
  • headers / custom_variables (необязательно): Объекты со строковыми значениями

reply-all-to-inbound-message

Отвечает на входящее сообщение и копирует остальных получателей исходного письма. Отправляет реальное письмо. Те же параметры, что и у reply-to-inbound-message.

Параметры:

  • inbox_id (обязательно): ID почтового ящика
  • message_id (обязательно): ID сообщения, на которое нужно ответить
  • Плюс те же необязательные поля отправки, что и у reply-to-inbound-message

forward-inbound-message

Пересылает входящее сообщение новым получателям. Отправляет реальное письмо.

Параметры:

  • inbox_id (обязательно): ID почтового ящика
  • message_id (обязательно): ID сообщения для пересылки
  • to (обязательно): Как минимум один получатель (строка с email или { email, name? }, либо массив)
  • Плюс те же необязательные поля отправки, что и у reply-to-inbound-message

list-inbound-threads

Выводит список цепочек переписки во входящем почтовом ящике (постранично через курсор). Возвращает форматированную сводку с подсказкой о следующей странице, если есть ещё результаты.

Параметры:

  • inbox_id (обязательно): ID почтового ящика
  • last_id (необязательно): Курсор пагинации из поля last_id предыдущего ответа

get-inbound-thread

Получает одну входящую цепочку с встроенными сообщениями (сначала самые старые). Возвращает полную запись цепочки в формате JSON.

Параметры:

  • inbox_id (обязательно): ID почтового ящика
  • thread_id (обязательно): ID цепочки

delete-inbound-thread

Безвозвратно удаляет входящую цепочку.

Параметры:

  • inbox_id (обязательно): ID почтового ящика
  • thread_id (обязательно): ID цепочки

Разработка

  1. Клонируйте репозиторий:
git clone https://github.com/mailtrap/mailtrap-mcp.git
cd mailtrap-mcp
  1. Установите зависимости:
npm install

Настройка с Claude Desktop или Cursor

[!TIP] Расположение файла конфигурации см. в разделе Setup.

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

{
  "mcpServers": {
    "mailtrap": {
      "command": "node",
      "args": ["/path/to/mailtrap-mcp/dist/index.js"],
      "env": {
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

Если вы используете asdf для управления Node.js, укажите абсолютный путь к исполняемому файлу:

(пример для Mac)

{
  "mcpServers": {
    "mailtrap": {
      "command": "/Users/<username>/.asdf/shims/node",
      "args": ["/path/to/mailtrap-mcp/dist/index.js"],
      "env": {
        "PATH": "/Users/<username>/.asdf/shims:/usr/bin:/bin",
        "ASDF_DIR": "/opt/homebrew/opt/asdf/libexec",
        "ASDF_DATA_DIR": "/Users/<username>/.asdf",
        "ASDF_NODEJS_VERSION": "20.6.1",
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

VS Code

[!TIP] Расположение файла конфигурации см. в разделе Setup.

{
  "mcp": {
    "servers": {
      "mailtrap": {
        "command": "node",
        "args": ["/path/to/mailtrap-mcp/dist/index.js"],
        "env": {
          "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
          "DEFAULT_FROM_EMAIL": "your_sender@example.com",
          "MAILTRAP_ACCOUNT_ID": "your_account_id",
          "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
        }
      }
    }
  }
}

Тестирование

Запуск инструментов против реального Mailtrap

Есть два способа проверить инструмент сквозным образом против реального аккаунта Mailtrap: браузерный интерфейс MCP Inspector для интерактивного исследования или его CLI-режим для разовых вызовов из командной строки.

Оба способа требуют предварительной сборки бандла:

npm run build

а также экспортированных в вашей оболочке переменных MAILTRAP_API_TOKEN и MAILTRAP_ACCOUNT_ID (скрипт mcp:cli передаёт обе переменные запущенному серверу).

Браузерный интерфейс

npm run dev

Inspector выводит URL вида http://localhost:6274. Откройте его, переключитесь на вкладку Tools, выберите инструмент (например, get-template), заполните параметры в формате JSON и нажмите Run. Ответ Mailtrap появится на панели ниже.

CLI

Для разовых вызовов без интерфейса используйте npm run mcp:cli. Передавайте флаги CLI Inspector после --, чтобы npm пересылал их без изменений:

# List all tools
npm run mcp:cli -- --method tools/list

# Call a tool — flags after the `--`
npm run mcp:cli -- \
  --method tools/call \
  --tool-name get-template \
  --tool-arg template_id=12345

# Multiple --tool-arg flags for tools with several params
npm run mcp:cli -- \
  --method tools/call \
  --tool-name send-sending-domain-setup-instructions \
  --tool-arg sending_domain_id=3938 \
  --tool-arg email=devops@example.com

Запуск MCPB-сервера

# Run the MCPB server directly
node dist/mcpb-server.js

# Or use the provided binary
mailtrap-mcpb-server

[!TIP] Для разработки с MCP Inspector:

npm run dev:mcpb

Обработка ошибок

Этот сервер использует структурированную обработку ошибок в соответствии с соглашениями MCP:

  • VALIDATION_ERROR: Ошибки валидации входных данных
  • CONFIGURATION_ERROR: Отсутствующая или недействительная конфигурация
  • EXECUTION_ERROR: Ошибки выполнения во время работы
  • TIMEOUT: Тайм-аут операции (по умолчанию 30 секунд)

Ошибки содержат практические сообщения и логируются в структурированном виде.

Безопасность

  • Входные данные валидируются через Zod-схемы
  • Переменные окружения обрабатываются безопасно
  • Защита от тайм-аута операций (30 секунд)
  • Конфиденциальные данные очищаются в выводе ошибок

Логирование

Структурированные JSON-логи с уровнями: INFO, WARN, ERROR, DEBUG.

Включите отладочное логирование, задав DEBUG=true.

# Example: enable debug logging
DEBUG=true node dist/mcpb-server.js

Важно: сервер записывает логи в stderr, чтобы stdout оставался зарезервированным для JSON-RPC-кадров. Это предотвращает ошибки парсинга JSON у хостов из-за перемешанных логов.

Пример анализа логов с помощью jq:

# Filter error logs
node dist/mcpb-server.js 2>&1 | jq 'select(.level == "error")'

# Filter debug logs
node dist/mcpb-server.js 2>&1 | jq 'select(.level == "debug")'

Устранение неполадок

Частые проблемы:

  1. Отсутствует API-токен: убедитесь, что задан MAILTRAP_API_TOKEN
  2. Песочница не работает: укажите test_inbox_id в вызове инструмента или задайте переменную окружения MAILTRAP_TEST_INBOX_ID
  3. Ошибки тайм-аута: проверьте сетевое подключение и статус API Mailtrap
  4. Ошибки валидации: убедитесь, что все обязательные поля заполнены

Участие в разработке

Отчёты об ошибках и pull request приветствуются на GitHub. Этот проект задуман как безопасное и гостеприимное пространство для сотрудничества; участники обязаны соблюдать кодекс поведения.

Лицензия

Пакет доступен как open source на условиях лицензии MIT.

Кодекс поведения

Все, кто взаимодействует с кодовыми базами проекта Mailtrap, трекерами задач, чатами и списками рассылки, обязаны следовать кодексу поведения.