Mailtrap MCP Server

официальный

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

GitHub
60

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

TypeScript test NPM

MCP-сервер Mailtrap

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

Необходимые условия

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

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

Обязательные переменные окружения:

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

Необязательные (можно передавать как параметры инструментов):

  • DEFAULT_FROM_EMAIL — адрес отправителя по умолчанию, если from не передан в send-email или send-sandbox-email. Позволяет менять отправителя при каждом вызове через параметр from.
  • MAILTRAP_TEST_INBOX_ID — ID тестового входящего ящика по умолчанию для инструментов песочницы, если test_inbox_id не передан. Позволяет переключаться между входящими ящиками при каждом вызове через параметр test_inbox_id.
  • MAILTRAP_SANDBOX_ID — ID песочницы по умолчанию для инструментов песочницы, если sandbox_id не передан. Позволяет переключаться между песочницами при каждом вызове через параметр 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": "[email protected]",
        "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": "[email protected]",
        "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": "[email protected]",
          "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/.

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

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

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

  • "Отправь письмо на [email protected] с темой 'Встреча завтра' и дружеским напоминанием о нашей предстоящей встрече."
  • "Напиши [email protected] об обновлении проекта и поставь в копию команду [email protected]"
  • "Отправь приветственный шаблон (uuid b81aabcd-1a1e-41cf-91b6-eca0254b3d96) на [email protected] с переменными { name: 'Alex' }"
  • "Отправь письмо в песочнице на [email protected] с темой 'Тестовый шаблон', чтобы посмотреть, как выглядит наше приветственное письмо"

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

  • "Покажи мои последние журналы отправленных писем"
  • "Покажи журналы писем, отправленных на [email protected]"
  • "Получи сообщение журнала письма для ID abc-123-uuid, чтобы проверить статус доставки"

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

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

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

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

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

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

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

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

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

send-email

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

Параметры:

  • from (необязательный): Отправитель в виде строки email или { email, name? }. Если не указан, используется DEFAULT_FROM_EMAIL.
  • to (необязательный): Получатель(и) — один email/{ email, name? } или массив. Необязателен, если указан cc или bcc; хотя бы один из to / cc / bcc должен содержать получателя.
  • cc (необязательный): Массив получателей CC (каждый — строка email или { email, name? }).
  • bcc (необязательный): Массив получателей BCC (каждый — строка email или { email, name? }).
  • 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 или { email, name? }. Возвращается к DEFAULT_FROM_EMAIL.
    • reply_to (необязательный): Адрес для ответа.
    • subject / text / html / category (необязательные, встроенный режим): Контент по умолчанию для каждого запроса.
    • template_uuid / template_variables (необязательные, режим шаблона): Шаблон + переменные по умолчанию. Взаимоисключающие с полями встроенного режима.
    • custom_variables (необязательный): Пользовательские переменные по умолчанию (строковые значения).
    • headers (необязательный): Пользовательские заголовки по умолчанию.
  • requests (обязательный): Непустой массив сообщений для каждого получателя. Каждая запись содержит:
    • to (необязательный): Получатель(и) — строка, { email, name? } или массив. Необязателен, если указан 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

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

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). Используйте list-email-logs для поиска ID сообщений.
  • include_content (необязательный): Если true, извлекает исходный EML (если доступен raw_message_url) и добавляет разобранные секции тела HTML и обычного текста, аналогично show-sandbox-email-message.

get-sending-stats

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

Параметры:

  • start_date (обязательный): Начальная дата для диапазона статистики (ГГГГ-ММ-ДД)
  • end_date (обязательный): Конечная дата для диапазона статистики (ГГГГ-ММ-ДД)
  • breakdown (необязательный): Способ разбивки статистики: aggregated (по умолчанию), by_domain, by_category, by_email_service_provider или by_date
  • sending_domain_ids (необязательный): Ограничить результаты указанными ID доменов-отправителей (массив целых чисел)
  • 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

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

Параметры:

  • template_id (обязательный): ID шаблона для получения

update-template

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

Параметры:

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

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

delete-template

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

Параметры:

  • template_id (обязательный): ID шаблона для удаления

send-sandbox-email

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

Параметры:

  • test_inbox_id (необязательный): ID тестового ящика Mailtrap. Обязателен, если не задан MAILTRAP_TEST_INBOX_ID; передаётся при вызове для указания конкретного ящика.
  • from (необязательный): Отправитель в виде строки email или { email, name? }. Если не указан, используется DEFAULT_FROM_EMAIL.
  • to (необязательный): Получатели в виде строки, разделённой запятыми, или массива строк email / объектов { email, name? }. Необязателен, если указан cc или bcc; хотя бы один из to / cc / bcc должен содержать получателя.
  • cc (необязательный): Массив получателей копии (каждый — строка email или { email, name? }).
  • bcc (необязательный): Массив получателей скрытой копии (каждый — строка email или { email, name? }).
  • 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.

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

get-sandbox-messages

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

Параметры:

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

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

show-sandbox-email-message

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

Параметры:

  • message_id (обязательный): ID сообщения песочницы для получения

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

get-sandbox-project

Получить проект песочницы по ID, включая его ящики и количество писем.

Параметры:

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

update-sandbox-project

Переименовать существующий проект песочницы.

Параметры:

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

list-sandboxes

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

Параметры:

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

mark-sandbox-as-read

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

Параметры:

  • sandbox_id (обязательный): ID песочницы для выполнения действия

reset-sandbox-credentials

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

Параметры:

  • sandbox_id (обязательный): ID песочницы для выполнения действия

enable-sandbox-email-address

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

Параметры:

  • sandbox_id (обязательный): ID песочницы для выполнения действия

reset-sandbox-email-address

Сгенерировать новый адрес для приёма писем для песочницы.

Параметры:

  • sandbox_id (обязательный): ID песочницы для выполнения действия

forward-sandbox-message

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

Параметры:

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

update-sandbox-message

Отметить сообщение песочницы как прочитанное или непрочитанное.

Параметры:

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

delete-sandbox-message

Удалить одно сообщение песочницы.

Параметры:

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

get-sandbox-message-spam-score

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

Параметры:

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

get-sandbox-message-html-analysis

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

Параметры:

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

get-sandbox-message-headers

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

Параметры:

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

get-sandbox-message-html

Получить отрендеренное HTML-тело сообщения песочницы.

Параметры:

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

get-sandbox-message-text

Получить текстовое тело сообщения песочницы.

Параметры:

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

get-sandbox-message-raw

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

Параметры:

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

get-sandbox-message-eml

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

Параметры:

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

get-sandbox-message-html-source

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

Параметры:

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

list-sandbox-attachments

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

Параметры:

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

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 (опционально): Фильтр по email. Возвращает только подавления, соответствующие этому адресу.

delete-suppression

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

Параметры:

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

list-webhooks

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

Параметры:

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

get-webhook

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

Параметры:

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

create-webhook

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

Параметры:

  • url (обязательный): URL, на который Mailtrap будет отправлять события вебхука
  • webhook_type (обязательный): "email_sending" или "audit_log"
  • active (опционально, boolean): по умолчанию 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 домена отправки, которым ограничивается этот вебхук

update-webhook

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

Параметры:

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

delete-webhook

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

Параметры:

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

get-contact

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

Параметры:

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

create-contact

Создать новый контакт.

Параметры:

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

update-contact

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

Параметры:

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

delete-contact

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

Параметры:

  • contact_identifier (обязательный): ID контакта или email

create-contact-event

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

Параметры:

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

list-contact-lists

Вывести все списки контактов для аккаунта.

Параметры:

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

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 (обязательный): Отображаемое имя (например, "Имя")
  • merge_tag (обязательный): Уникальное имя заполнителя (например, first_name)
  • data_type (обязательный): Одно из text, number, boolean, date

update-contact-field

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

Параметры:

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

delete-contact-field

Безвозвратно удалить определение поля контакта по ID.

Параметры:

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

create-contact-import

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

Параметры:

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

get-contact-import

Получить статус задания импорта контактов (создано/запущено/завершено/не удалось) с количеством созданных/обновленных/сверх лимита.

Параметры:

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

create-contact-export

Экспортировать контакты, соответствующие набору фильтров, объединенных по И. Возвращает запись задания экспорта; опрашивайте статус с помощью 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 (admin) или 10 (viewer)

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 (обязательный): Отображаемое имя для новой суб-учетной записи

Разработка

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

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

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

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

{
  "mcpServers": {
    "mailtrap": {
      "command": "node",
      "args": ["/path/to/mailtrap-mcp/dist/index.js"],
      "env": {
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "[email protected]",
        "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": "[email protected]",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

VS Code

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

{
  "mcp": {
    "servers": {
      "mailtrap": {
        "command": "node",
        "args": ["/path/to/mailtrap-mcp/dist/index.js"],
        "env": {
          "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
          "DEFAULT_FROM_EMAIL": "[email protected]",
          "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 protected]

Запуск сервера 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-запросы приветствуются на GitHub. Этот проект призван быть безопасным и дружелюбным пространством для сотрудничества, и от участников ожидается соблюдение кодекса поведения.

Лицензия

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

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

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