Mailgun MCP Server

официальный

Взаимодействие с API Mailgun.

GitHub
56

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

Mailgun MCP Server

MCP

Обзор

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

Примечание: Этот MCP-сервер работает локально на вашем компьютере. Mailgun в настоящее время не предлагает размещенную версию этого сервера.

Возможности

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

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

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

Быстрый старт

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

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

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

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

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

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

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

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

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

Через флаг 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"
}

Обнаруживаемость — запустите бинарный файл с --list-tags, чтобы вывести поддерживаемые значения тегов, или с --help для полной справки. Неизвестные теги отклоняются при запуске с четким сообщением об ошибке.

Пути конфигурации для конкретных клиентов

  • Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
  • Claude Desktop (Windows): %APPDATA%/Claude/claude_desktop_config.json
  • Claude Code: Запустите claude mcp add или отредактируйте ~/.claude.json

Примеры промптов

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

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

Примечание: некоторым 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: [email protected], [email protected].

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

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.

Разработка

Для запуска из исходного кода клонируйте репозиторий и используйте node напрямую:

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

В конфигурации вашего MCP-клиента замените команду npx на:

"command": "node",
"args": ["/path/to/mailgun-mcp-server/src/mailgun-mcp.js"]

Pre-commit хуки

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

Примечание о добавлении endpoints

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

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

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

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

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

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

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

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

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

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

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

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

URL вебхуков

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

Валидация ввода

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

Отладка

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

Лицензия

Apache 2.0 — подробности см. в LICENSE.

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

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