Mailgun MCP Server

officiel

Interagir avec l'API Mailgun.

GitHub
56

Documentation

Serveur MCP Mailgun

MCP

Aperçu

Un serveur Model Context Protocol (MCP) pour Mailgun qui offre aux agents IA une interface pratique et orientée flux de travail pour envoyer des e-mails, diagnostiquer la délivrabilité et gérer les opérations du compte.

Remarque : Ce serveur MCP s'exécute localement sur votre machine. Mailgun ne propose pas actuellement de version hébergée de ce serveur.

Capacités

  • Messagerie — Envoyer des e-mails, récupérer les messages stockés, renvoyer des messages
  • Domaines — Afficher les détails du domaine, vérifier la configuration DNS, gérer les paramètres de suivi (clic, ouverture, désabonnement)
  • Webhooks — Lister, créer, mettre à jour et supprimer les webhooks d'événements
  • Routes — Afficher et mettre à jour les règles de routage des e-mails entrants
  • Listes de diffusion — Créer et gérer des listes de diffusion et leurs membres
  • Modèles — Créer et gérer des modèles d'e-mail avec gestion des versions
  • Analytique — Interroger les métriques d'envoi, les métriques d'utilisation et les journaux
  • Statistiques — Afficher les statistiques agrégées par domaine, étiquette, fournisseur, appareil et pays
  • Suppressions — Afficher les rebonds, désabonnements, plaintes et entrées de la liste autorisée
  • IP et pools d'IP — Afficher les affectations d'IP et la configuration des pools d'IP dédiés
  • Classification des rebonds — Analyser les types de rebonds et les problèmes de livraison

Prérequis

  • Node.js (v20.12 ou supérieur)
  • Compte Mailgun et clé API

Démarrage rapide

Configuration

Ajoutez ce qui suit à la configuration de votre client MCP :

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

Variables d'environnement

VariableRequisePar défautDescription
MAILGUN_API_KEYOui—Votre clé API Mailgun
MAILGUN_API_REGIONNonusRégion API : us ou eu
MAILGUN_MCP_TAGSNon(tous)Étiquettes de produit séparées par des virgules à activer. Équivalent à --tags. L'option CLI est prioritaire.

Filtrage par étiquette

Vous pouvez limiter les outils enregistrés par le serveur à une ou plusieurs étiquettes de produit Mailgun. Cela est utile pour restreindre l'ensemble d'outils présenté au modèle — par exemple, n'exposer que les outils de validation à un flux de travail qui n'a pas besoin des capacités d'envoi.

Étiquettes valides : send, validate, optimize, inspect. Lorsqu'aucune n'est spécifiée, tous les outils sont enregistrés (comportement par défaut actuel).

Le filtrage utilise une sémantique OU : un outil est enregistré si l'une de ses étiquettes apparaît dans l'ensemble actif.

Via l'option CLI — passez --tags dans le champ args de la configuration de votre client MCP :

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

Via la variable d'environnement — définissez MAILGUN_MCP_TAGS (l'option CLI est prioritaire si les deux sont présentes) :

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

Découvrabilité — exécutez le binaire avec --list-tags pour afficher les valeurs d'étiquette prises en charge, ou --help pour l'aide complète. Les étiquettes inconnues sont rejetées au démarrage avec un message d'erreur clair.

Chemins de configuration spécifiques au client

  • Claude Desktop (macOS) : ~/Library/Application Support/Claude/claude_desktop_config.json
  • Claude Desktop (Windows) : %APPDATA%/Claude/claude_desktop_config.json
  • Claude Code : Exécutez claude mcp add ou modifiez ~/.claude.json

Exemples d'invites

Envoyer un e-mail

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

Remarque : certains clients MCP nécessitent un forfait payant pour invoquer des outils qui envoient des données. Si l'envoi échoue silencieusement, vérifiez le forfait de votre client.

Récupérer et visualiser les statistiques d'envoi

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

Gérer les modèles

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

Enquêter sur la délivrabilité

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

Dépanner le DNS

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

Examiner les suppressions

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

Gérer les règles de routage

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

Créer une liste de diffusion

Create a mailing list called announcements@DOMAIN_HERE and add these
members: [email protected], [email protected].

Comparer les domaines

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

Engagement par région

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

Examiner les paramètres de suivi

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

Développement

Pour exécuter à partir des sources, clonez le dépôt et utilisez directement node :

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

Dans la configuration de votre client MCP, remplacez la commande npx par :

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

Hooks de pré-commit

npm install installe un hook git de pré-commit (via husky) qui exécute oxlint --fix et oxfmt sur les fichiers TypeScript/JavaScript stagés et exécute npm run check:versions. Les problèmes corrigibles sont automatiquement corrigés et ré-stagés ; les commits qui introduisent des erreurs de lint non corrigibles ou des incohérences de synchronisation de version sont rejetés. Si vous aviez déjà un clone local avant cette modification, exécutez npm install une fois pour installer le hook.

Remarque sur l'ajout de points de terminaison

Lors de l'ajout d'un nouveau point de terminaison, si vous utilisez une chaîne simple pour sa définition, il sera par défaut étiqueté avec le type de produit send dans le champ _meta. Si vous souhaitez l'étiqueter comme un produit différent, utilisez la version objet du type EndpointEntry.

Considérations de sécurité

Isolation de la clé API

Votre clé API Mailgun est transmise en tant que variable d'environnement et n'est jamais exposée au modèle d'IA lui-même — elle est uniquement utilisée par le processus du serveur MCP pour authentifier les requêtes. Le serveur n'enregistre pas les clés API, les paramètres de requête ou les données de réponse.

Exécution locale

Le serveur s'exécute localement sur votre machine. Toute communication avec l'API Mailgun se fait via HTTPS avec validation du certificat TLS appliquée. Aucune donnée n'est envoyée à des services tiers au-delà de l'API Mailgun.

Permissions de la clé API

Utilisez une clé API Mailgun dédiée avec des permissions limitées aux seules opérations dont vous avez besoin. Le serveur expose des opérations de lecture et de mise à jour mais n'expose aucune opération de suppression, ce qui limite le rayon d'action des actions non intentionnelles.

Limitation de débit

Le serveur n'implémente pas de limitation de débit côté client. Chaque appel d'outil de l'IA se traduit directement par une requête à l'API Mailgun. Le serveur s'appuie sur les limites de débit côté serveur de Mailgun pour prévenir les abus — les requêtes qui dépassent ces limites renverront une erreur à l'assistant IA.

Injection d'invite

Comme pour tout serveur MCP, une invite conçue ou contradictoire pourrait amener l'assistant IA à appeler des opérations que vous n'aviez pas prévues — par exemple, modifier les paramètres de suivi ou lire les membres d'une liste de diffusion. Examinez les confirmations d'appel d'outil de votre assistant IA avant d'approuver les actions, en particulier dans des contextes d'invite non fiables.

URL de webhook

Les opérations de création et de mise à jour de webhook acceptent des URL arbitraires fournies par l'assistant IA. Le serveur MCP transmet ces URL à l'API Mailgun sans validation supplémentaire. Mailgun est responsable de la validation des destinations de webhook. Assurez-vous que votre assistant IA ne définit pas d'URL de webhook pointant vers des adresses internes ou sensibles non prévues.

Validation des entrées

Tous les paramètres d'outil sont validés par rapport à la spécification OpenAPI de Mailgun en utilisant des schémas Zod. Cependant, la validation dépend de l'exactitude de la spécification OpenAPI, et certains paramètres de cas limites peuvent revenir à une validation permissive. L'API Mailgun effectue sa propre validation côté serveur comme couche de protection supplémentaire.

Débogage

Le serveur MCP communique via stdio. Reportez-vous au Guide de débogage MCP pour le dépannage.

Licence

Apache 2.0 — voir LICENSE pour plus de détails.

Contribution

Nous accueillons les contributions avec plaisir ! N'hésitez pas à soumettre une Pull Request ou à ouvrir un Issue.