Mailgun

Mailgun MCP-сервер

Обзор

Model Context Protocol (MCP) сервер для Mailgun, который предоставляет AI-агентам практичный, ориентированный на рабочие процессы интерфейс для отправки писем, диагностики доставляемости и управления операциями с аккаунтом.

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

Возможности

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

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

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

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

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

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

• 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 в командной строке). По умолчанию используется 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	Нет	(все)	Список продуктовых тегов через запятую для включения. Эквивалент --tags. Флаг командной строки имеет приоритет.

Параметры командной строки

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

Флаг	Описание
--tags <list>	Список продуктовых тегов через запятую для включения (по умолчанию: все). Допустимые: send, validate, optimize, inspect.
--list-tags	Вывести допустимые значения тегов и выйти.
--help, -h	Показать справку и выйти.

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

Вы можете ограничить набор инструментов, регистрируемых сервером, одним или несколькими продуктовыми тегами Mailgun. Это полезно для сужения набора инструментов, показываемых модели — например, для предоставления только инструментов валидации рабочему процессу, которому не нужны возможности отправки.

Допустимые теги: send, validate, optimize, inspect. Если не указано, регистрируются все инструменты (текущее поведение по умолчанию).

Фильтрация использует семантику ИЛИ: инструмент регистрируется, если любой из его тегов присутствует в активном наборе.

Через флаг командной строки — передайте --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 (флаг командной строки имеет приоритет, если указаны оба):

"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.

Проверка размещения во входящих (Оптимизация)

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

Предпросмотр письма (Инспекция)

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 позволяет вам использовать инструменты без полноценного клиента. Сначала соберите, затем запустите его для собранного сервера:

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

Хуки pre-commit

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

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

При добавлении новой конечной точки, если вы используете простую строку для ее определения, по умолчанию она будет помечена типом продукта send в поле _meta. Если вы хотите пометить ее как другой продукт, используйте объектную версию типа EndpointEntry.

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

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

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

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

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

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

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

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

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

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

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

URL-адреса вебхуков

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

Валидация входных данных

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

Отладка

MCP-сервер взаимодействует через stdio. Обратитесь к Руководству по отладке MCP для устранения неполадок.

Лицензия

Apache 2.0 — см. LICENSE для подробностей.

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

Мы приветствуем вклад! Пожалуйста, не стесняйтесь отправлять Pull Request или открывать Issue.