Mailgun

MCP-сервер Mailgun

Обзор

MCP-сервер для Mailgun, реализующий Model Context Protocol и предоставляющий ИИ-агентам практичный интерфейс, ориентированный на рабочие процессы: отправку электронной почты, диагностику доставляемости и управление операциями с аккаунтом.

[!NOTE] Этот MCP-сервер работает локально на вашем компьютере и обменивается данными через stdio. В настоящее время Mailgun не предлагает размещённую версию этого сервера.

Возможности

• Обмен сообщениями — отправка писем, получение сохранённых сообщений, повторная отправка сообщений
• Домены — просмотр сведений о доменах, проверка конфигурации DNS, управление настройками отслеживания (переходы по ссылкам, открытия, отписки)
• Вебхуки — просмотр, создание и обновление вебхуков событий
• Маршруты — просмотр и обновление правил маршрутизации входящей почты
• Списки рассылки — создание, просмотр и обновление списков рассылки и их участников
• Шаблоны — создание, просмотр и обновление шаблонов писем с управлением версиями
• Аналитика — запрос метрик отправки, метрик использования и журналов
• Статистика — просмотр сводной статистики по домену, тегу, провайдеру, устройству и стране
• Подавления — просмотр отказов доставки, отписок, жалоб и записей списка разрешённых адресов
• IP-адреса и пулы IP-адресов — просмотр назначений IP-адресов и конфигурации пулов выделенных IP-адресов
• Классификация отказов доставки — анализ типов отказов доставки и проблем с доставкой
• Проверка — проверка доставляемости и синтаксиса адреса электронной почты перед отправкой (validate)
• Оптимизация (размещение во входящих) — получение результатов тестов размещения во входящих и тестов с контрольными адресами для оценки доставляемости (optimize)
• Проверка (предварительный просмотр письма) — получение результатов тестов отображения и предварительного просмотра писем в разных почтовых клиентах (inspect)
• Лимиты аккаунта — просмотр индивидуальных месячных лимитов отправки

Указанные выше метки (validate, optimize, inspect) — это теги продуктов, используемые для фильтрации по тегам. Все остальные возможности зарегистрированы под тегом send, который разделён на send.<group> наборов инструментов.

[!NOTE] Инструменты доступны только для чтения и обновления — операции удаления не предоставляются, что снижает последствия непреднамеренных действий. См. раздел Вопросы безопасности.

Как это работает

Сервер работает на основе OpenAPI. При запуске он анализирует встроенную спецификацию OpenAPI Mailgun и регистрирует выбранный список разрешённых конечных точек как инструменты MCP, создавая схему входных данных каждого инструмента (с помощью Zod) на основе спецификации. Для каждого инструмента указываются тег продукта Mailgun (send, validate, optimize или inspect), набор инструментов, к которому он относится, и возможность только чтения данных.

По умолчанию сервер загружает все инструменты при запуске. С --tags dynamic он загружает небольшой основной набор инструментов и три инструмента, с помощью которых модель может по запросу загружать дополнительные наборы инструментов. Это позволяет сократить объём определений инструментов, передаваемых модели. Вместо этого фильтрация по тегам загружает при запуске фиксированный набор инструментов, чтобы для конкретного рабочего процесса можно было предоставить только необходимые продукты.

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

• Node.js (v20.12 или выше)
• Аккаунт Mailgun и ключ API

Установка

Сервер опубликован в npm как @mailgun/mcp-server и работает через stdio. Большинство клиентов могут запускать его по запросу с помощью npx, поэтому устанавливать его глобально не нужно. В каждом примере ниже замените YOUR-mailgun-api-key ключом из раздела настроек безопасности API Mailgun.

[!TIP] Если ваш аккаунт размещён в европейском регионе Mailgun, добавьте "MAILGUN_API_REGION": "eu" в блок env (или -e MAILGUN_API_REGION=eu в CLI). По умолчанию используется us.

Claude Code

claude mcp add mailgun -e MAILGUN_API_KEY=YOUR-mailgun-api-key -- npx -y @mailgun/mcp-server

Затем выполните /mcp в Claude Code, чтобы убедиться, что сервер mailgun подключён.

Claude Desktop

Откройте Settings → Developer → Edit Config или отредактируйте файл напрямую:

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

{
  "mcpServers": {
    "mailgun": {
      "command": "npx",
      "args": ["-y", "@mailgun/mcp-server"],
      "env": {
        "MAILGUN_API_KEY": "YOUR-mailgun-api-key",
        "MAILGUN_API_REGION": "us"
      }
    }
  }
}

Cursor

Откройте палитру команд и выберите Cursor Settings → MCP → Add new global MCP server, затем добавьте:

{
  "mcpServers": {
    "mailgun": {
      "command": "npx",
      "args": ["-y", "@mailgun/mcp-server"],
      "env": {
        "MAILGUN_API_KEY": "YOUR-mailgun-api-key"
      }
    }
  }
}

Codex

codex mcp add mailgun \
  --env MAILGUN_API_KEY=YOUR-mailgun-api-key \
  -- npx -y @mailgun/mcp-server

VS Code (GitHub Copilot)

Добавьте следующий фрагмент в файл settings.json:

{
  "mcp": {
    "servers": {
      "mailgun": {
        "command": "npx",
        "args": ["-y", "@mailgun/mcp-server"],
        "env": {
          "MAILGUN_API_KEY": "YOUR-mailgun-api-key"
        }
      }
    }
  }
}

Windsurf

{
  "mcpServers": {
    "mailgun": {
      "command": "npx",
      "args": ["-y", "@mailgun/mcp-server"],
      "env": {
        "MAILGUN_API_KEY": "YOUR-mailgun-api-key"
      }
    }
  }
}

Gemini CLI

Добавьте в файл ~/.gemini/settings.json:

{
  "mcpServers": {
    "mailgun": {
      "command": "npx",
      "args": ["-y", "@mailgun/mcp-server"],
      "env": {
        "MAILGUN_API_KEY": "YOUR-mailgun-api-key"
      }
    }
  }
}

Конфигурация

Переменные среды

Переменная	Обязательная	Значение по умолчанию	Описание
MAILGUN_API_KEY	Да	—	Ваш ключ API Mailgun
MAILGUN_API_REGION	Нет	us	Регион API: us или eu
MAILGUN_API_HOSTNAME	Нет	(определяется по региону)	Переопределение имени хоста API (например, api.eu.mailgun.net). Имеет приоритет над регионом.
MAILGUN_MCP_TAGS	Нет	(все)	Разделённые запятыми теги или наборы инструментов для загрузки либо dynamic для основных инструментов с загрузкой дополнительных по запросу. Эквивалент --tags. Флаг CLI имеет приоритет.

Параметры CLI

Передавайте флаги после имени пакета в args клиента (например, ["-y", "@mailgun/mcp-server", "--tags", "validate,inspect"]).

Флаг	Описание
--tags <list>	Разделённые запятыми теги или наборы инструментов для загрузки (по умолчанию: все). Допустимые значения: all, dynamic, core, send, validate, optimize, inspect и наборы инструментов send.<group>.
--list-tags	Вывести все допустимые значения --tags с описаниями и завершить работу.
--help, -h	Показать справку и завершить работу.

Наборы инструментов по запросу

С параметром --tags dynamic (или MAILGUN_MCP_TAGS=dynamic) сервер запускается со следующими основными инструментами:

Инструмент	Назначение
post-v3-domain-messages	Отправка письма
get-v4-domains	Список доменов
get-v4-domains-name	Сведения о домене и записи DNS
put-v4-domains-name-verify	Повторная проверка записей DNS домена
get-v3-domains-name-tracking	Настройки отслеживания
get_metrics_summary	Сводка основных метрик отправки
post-v1-analytics-metrics	Запрос метрик аккаунта
post-v1-analytics-logs	Запрос журналов событий
post-v2-bounce-classification-metrics	Метрики классификации отказов доставки
get-v3-domain-bounces	Список отказов доставки
get-v3-domain-bounces-address	Поиск записи об отказе доставки
get-v3-domain-unsubscribes	Список отписок
get-v3-domain-complaints	Список жалоб
get-v3-domain-templates	Список шаблонов
validate_email	Проверка адреса электронной почты

Каждый инструмент относится к набору инструментов. Когда задача этого требует, модель загружает остальные инструменты набора:

Набор инструментов	Инструменты	Содержимое
send.messages	3	Отправка писем; получение и повторная отправка сохранённых сообщений
send.domains	8	Домены, проверка DNS, очереди отправки, настройки отслеживания
send.webhooks	4	Вебхуки доменов
send.account	8	IP-адреса аккаунта, пулы выделенных IP-адресов, индивидуальные лимиты отправки
send.message_tags	8	Теги сообщений, статистика по тегам, лимиты тегов
send.analytics	12	Статистика и сводные данные, метрики и журналы аналитики, классификация отказов доставки
send.suppressions	8	Отказы доставки, отписки, жалобы, список разрешённых адресов
send.routes	3	Маршруты входящей почты
send.lists	8	Списки рассылки и участники
send.templates	8	Шаблоны и версии шаблонов
validate	1	Проверка адреса электронной почты
optimize	1	Результаты теста размещения во входящих
inspect	1	Результаты теста предварительного просмотра письма

Модель загружает наборы инструментов с помощью трёх дополнительных инструментов:

• mailgun_list_toolsets выводит список всех наборов инструментов и входящих в них инструментов, отмечая, какие из них загружены и какие изменяют данные. Если указать имя инструмента, вместо этого возвращается его схема входных данных.
• mailgun_enable_toolset загружает один или несколько наборов инструментов. Затем сервер уведомляет клиента об изменении списка инструментов (notifications/tools/list_changed), и новые инструменты появляются рядом с основными. В ответе перечислены новые инструменты без их схем входных данных; схемы поступают вместе с обновлённым списком инструментов.
• mailgun_call_tool запускает инструмент только для чтения по имени независимо от того, загружен ли его набор инструментов. Это запасной вариант для клиентов, которые не обновляют список инструментов после изменений. Он не запускает основные инструменты и инструменты, изменяющие данные, поэтому они всегда вызываются отдельно.

Загруженные наборы инструментов остаются доступными, пока клиент не отключится. Для загрузки по запросу нужен клиент, который обновляет список инструментов после уведомления сервера об изменениях; Claude Code это поддерживает. В клиентах, которые этого не делают, новые инструменты не появятся: инструменты только для чтения по-прежнему доступны через mailgun_call_tool, а для инструментов, изменяющих данные, потребуется режим по умолчанию (все инструменты) или --tags, например --tags core,send.templates.

Фильтрация по тегам

Если задать для --tags или MAILGUN_MCP_TAGS любое значение, кроме dynamic, при запуске будут загружены только соответствующие инструменты, без инструментов загрузки. Используйте этот параметр, чтобы ограничить список инструментов, показываемых модели (например, оставить только инструменты проверки в рабочем процессе, где не отправляются письма).

Допустимые значения (описания можно посмотреть, выполнив --list-tags):

• all — все инструменты (по умолчанию)
• dynamic — основные инструменты, а остальные наборы загружаются по запросу. Используйте это значение отдельно; при сочетании с другими значениями запуск завершится ошибкой.
• core — только перечисленные выше основные инструменты
• send, validate, optimize, inspect — все инструменты для соответствующего продукта (send охватывает все наборы инструментов send.<group>)
• Идентификатор набора инструментов, например send.templates

Фильтрация использует логику ИЛИ: инструмент загружается, если соответствует хотя бы одному значению из списка. Например, core,send.templates загружает основные инструменты и все инструменты для работы с шаблонами.

Через флаг CLI — передайте --tags в args конфигурации клиента MCP:

{
  "mcpServers": {
    "mailgun": {
      "command": "npx",
      "args": ["-y", "@mailgun/mcp-server", "--tags", "validate,inspect"],
      "env": {
        "MAILGUN_API_KEY": "YOUR-mailgun-api-key"
      }
    }
  }
}

Через переменную среды — задайте MAILGUN_MCP_TAGS (если указаны оба параметра, приоритет имеет флаг CLI):

"env": {
  "MAILGUN_API_KEY": "YOUR-mailgun-api-key",
  "MAILGUN_MCP_TAGS": "validate,inspect"
}

[!TIP] Запустите исполняемый файл с --list-tags, чтобы вывести все допустимые значения, или с --help, чтобы показать полную справку. При запуске неизвестные значения отклоняются с понятным сообщением об ошибке.

Примеры запросов

Отправка письма

Can you send an email to EMAIL_HERE with a funny email body that makes it sound
like it's from the IT Desk from Office Space? Please use the sending domain
DOMAIN_HERE, and make the email from "postmaster@DOMAIN_HERE"!

[!NOTE] Для вызова инструментов, отправляющих данные, некоторым MCP-клиентам требуется платный тариф. Если отправка завершается без сообщения об ошибке, проверьте тариф своего клиента.

Получение и визуализация статистики отправки

Would you be able to make a chart with email delivery statistics for the past week?

Управление шаблонами

Create a welcome email template for new signups on my domain DOMAIN_HERE.
Include a personalized greeting and a call-to-action button.

Анализ доставляемости

Can you check the bounce classification stats for my account and tell me
what the most common bounce reasons are?

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

Check the DNS verification status for my domain DOMAIN_HERE and tell me
if anything needs fixing.

Проверка списков подавления

Are there any unsubscribes or complaints for DOMAIN_HERE? Summarize the
top offenders.

Управление правилами маршрутизации

List all my inbound routes and explain what each one does.

Создание списка рассылки

Create a mailing list called announcements@DOMAIN_HERE and add these
members: alice@example.com, bob@example.com.

Сравнение доменов

Compare my sending volume and delivery rates across all my domains for
the past month.

Вовлечённость по регионам

Break down my email engagement by country and device for DOMAIN_HERE.

Проверка настроек отслеживания

List all my domains and show which ones have tracking enabled for clicks
and opens.

Проверка адреса электронной почты

Validate the email address EMAIL_HERE and tell me whether it's safe to send to.

Проверка попадания во входящие (Optimize)

Pull the inbox placement results for seed test RESULT_ID_HERE and summarize
where my message landed (inbox, spam, or missing) by provider.

Предварительный просмотр письма (Inspect)

Get the email preview results for test TEST_ID_HERE and tell me if the email
renders correctly across clients.

Разработка

Запуск из исходного кода

Сервер написан на TypeScript. Клонируйте репозиторий, установите зависимости, соберите проект и запустите тесты:

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

npm run build компилирует src/ в dist/ и копирует собранную спецификацию OpenAPI. Укажите в настройках MCP-клиента собранную точку входа вместо npx (используйте абсолютный путь):

{
  "mcpServers": {
    "mailgun": {
      "command": "node",
      "args": ["/absolute/path/to/mailgun-mcp-server/dist/mailgun-mcp.js"],
      "env": {
        "MAILGUN_API_KEY": "YOUR-mailgun-api-key"
      }
    }
  }
}

Тестирование в процессе разработки

MCP-серверы — это долгоживущие процессы stdio, которые не поддерживают горячую перезагрузку. Поэтому цикл работы такой: пересобирайте проект после каждого сохранения, а затем переподключайте клиент, чтобы применить изменения.

1. Один раз запустите npm run build, чтобы подготовить dist/openapi.yaml.

2. Оставьте компилятор TypeScript запущенным, чтобы он пересобирал dist/ после каждого сохранения:

   npx tsc --watch
   

3. Укажите в отдельном MCP-клиенте (или MCP Inspector, описанном ниже) путь к dist/mailgun-mcp.js. После внесения изменений перезапустите сеанс MCP-клиента, чтобы загрузить новую сборку.

Тестирование с помощью MCP Inspector

MCP Inspector позволяет проверять инструменты без полноценного клиента. Сначала соберите проект, затем запустите Inspector для собранного сервера:

npm run build
MAILGUN_API_KEY=YOUR-mailgun-api-key npx @modelcontextprotocol/inspector node dist/mailgun-mcp.js

Откройте интерфейс Inspector, нажмите Connect, а затем выберите List Tools, чтобы убедиться, что сервер работает. Чтобы проверить отфильтрованный набор инструментов, добавьте флаги после пути к серверу:

MAILGUN_API_KEY=YOUR-mailgun-api-key npx @modelcontextprotocol/inspector node dist/mailgun-mcp.js --tags validate,inspect

Хуки перед коммитом

npm install устанавливает git-хук pre-commit (с помощью husky), который запускает oxlint --fix и oxfmt для подготовленных к коммиту файлов TypeScript/JavaScript, а также запускает npm run check:versions. Исправимые проблемы устраняются автоматически, а файлы повторно добавляются в индекс; коммиты с неисправимыми ошибками линтера или несоответствиями синхронизации версий отклоняются. Если вы клонировали репозиторий до этого изменения, один раз запустите npm install, чтобы установить хук.

Примечание о добавлении конечных точек

Конечные точки сгруппированы по наборам инструментов в endpointGroups. Для обычной строковой записи тег продукта берётся из набора инструментов (send.templates → send), а запись считается доступной только для чтения, лишь если это GET. Используйте объектную форму EndpointEntry, чтобы задать имя инструмента, пометить инструмент как core (загружается при запуске в динамическом режиме) или пометить POST, который только запрашивает данные, как readOnly: true.

Вопросы безопасности

Изоляция API-ключа

Ваш API-ключ Mailgun передаётся как переменная среды и никогда не раскрывается самой модели ИИ — он используется только процессом MCP-сервера для аутентификации запросов. Сервер не записывает в журналы API-ключи, параметры запросов или данные ответов.

Локальное выполнение

Сервер работает локально на вашем компьютере. Весь обмен данными с API Mailgun выполняется по HTTPS с обязательной проверкой сертификата TLS. Данные не отправляются сторонним сервисам, кроме API Mailgun.

Разрешения API-ключа

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

Ограничение частоты запросов

Сервер не реализует ограничение частоты запросов на стороне клиента. Каждый вызов инструмента ИИ напрямую преобразуется в запрос к API Mailgun. Для предотвращения злоупотреблений сервер полагается на ограничения частоты запросов на стороне Mailgun — запросы, превышающие эти ограничения, вернут ошибку ИИ-ассистенту.

Внедрение промптов

Как и любой MCP-сервер, этот сервер может быть подвержен тщательно составленным или враждебным промптам, которые заставят ИИ-ассистента вызвать непредусмотренные операции — например, изменить настройки отслеживания или прочитать участников списка рассылки. Перед подтверждением действий проверяйте запросы ИИ-ассистента на вызов инструментов, особенно если промпт поступил из ненадёжного источника.

Загрузка инструментов и подтверждения

Каждый инструмент содержит аннотацию MCP readOnlyHint, поэтому клиенты могут отличать инструменты, которые только читают данные, от инструментов, которые их изменяют (например, при запросе подтверждения). mailgun_list_toolsets и mailgun_call_tool доступны только для чтения. mailgun_enable_toolset меняет набор инструментов, доступных сеансу, поэтому не помечен как доступный только для чтения, но при этом ничего не меняет в Mailgun. mailgun_call_tool запускает только инструменты, доступные только для чтения и не входящие в основной набор, поэтому его подтверждение никогда не приведёт к отправке писем или изменению настроек аккаунта. Инструменты, изменяющие данные, всегда выполняются отдельным вызовом.

Загрузка наборов инструментов по запросу сокращает объём информации, доступной модели; это не средство контроля доступа, поскольку модель может загрузить любой набор инструментов. Чтобы ограничить набор инструментов, доступных серверу, используйте --tags.

URL вебхуков

Операции создания и обновления вебхуков принимают произвольные URL, переданные через ИИ-ассистента. MCP-сервер передаёт эти URL в API Mailgun без дополнительной проверки. Проверку адресов назначения вебхуков выполняет Mailgun. Убедитесь, что ИИ-ассистент не задаёт URL вебхуков, указывающие на непредусмотренные внутренние или конфиденциальные адреса.

Проверка входных данных

Все параметры инструментов проверяются по спецификации OpenAPI Mailgun с помощью схем Zod. Однако проверка зависит от точности спецификации OpenAPI, и для некоторых граничных параметров может применяться менее строгая проверка. API Mailgun выполняет собственную проверку на стороне сервера в качестве дополнительного уровня защиты.

Отладка

MCP-сервер обменивается данными через stdio. Инструкции по устранению неполадок см. в руководстве по отладке MCP.

Лицензия

Apache 2.0 — подробности см. в файле LICENSE.

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

Мы приветствуем ваш вклад! Вы можете отправить Pull Request или создать Issue.