Mailgun

Serveur MCP Mailgun

Aperçu

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

[!NOTE] Ce serveur MCP s'exécute localement sur votre machine et communique via stdio. 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 et mettre à jour les webhooks d'événements
• Routes — Afficher et mettre à jour les règles de routage des e-mails entrants
• Listes de diffusion — Créer, afficher et mettre à jour les listes de diffusion et leurs membres
• Modèles — Créer, afficher et mettre à jour les modèles d'e-mails 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ées
• Classification des rebonds — Analyser les types de rebonds et les problèmes de livraison
• Validation — Valider la délivrabilité et la syntaxe de l'adresse e-mail avant l'envoi (validate)
• Optimiser (Placement en boîte de réception) — Récupérer les résultats des tests de placement/seed pour évaluer la délivrabilité (optimize)
• Inspecter (Aperçu de l'e-mail) — Récupérer les résultats des tests de rendu et d'aperçu d'e-mail sur différents clients (inspect)
• Limites du compte — Afficher les limites d'envoi mensuelles personnalisées

Les étiquettes entre parenthèses ci-dessus (validate, optimize, inspect) sont les balises produit utilisées par le filtrage par balise. Toutes les autres capacités sont enregistrées sous la balise send.

[!NOTE] Les outils sont limités aux opérations de lecture et de mise à jour — aucune opération de suppression n'est exposée, ce qui limite le rayon d'action d'une action non intentionnelle. Voir Considérations de sécurité.

Fonctionnement

Le serveur est piloté par OpenAPI. Au démarrage, il analyse une spécification OpenAPI Mailgun intégrée et enregistre une liste autorisée d'endpoints en tant qu'outils MCP, générant le schéma d'entrée de chaque outil (via Zod) à partir de la spécification. Chaque outil est annoté avec une balise produit Mailgun (send, validate, optimize ou inspect). Tous les outils correspondants sont enregistrés dès le départ — il n'y a pas de chargement paresseux ou à la demande. Le filtrage par balise est appliqué au démarrage pour délimiter quels outils sont enregistrés, afin qu'un flux de travail donné puisse exposer uniquement les produits dont il a besoin.

Prérequis

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

Installation

Le serveur est publié sur npm sous le nom @mailgun/mcp-server et s'exécute via stdio. La plupart des clients peuvent le lancer à la demande avec npx, il n'y a donc rien à installer globalement. Dans chaque extrait ci-dessous, remplacez YOUR-mailgun-api-key par une clé provenant de vos paramètres de sécurité de l'API Mailgun.

[!TIP] Si votre compte est hébergé dans la région EU de Mailgun, ajoutez "MAILGUN_API_REGION": "eu" au bloc env (ou -e MAILGUN_API_REGION=eu sur la CLI). La valeur par défaut est us.

Claude Code

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

Ensuite, exécutez /mcp dans Claude Code pour confirmer que le serveur mailgun est connecté.

Claude Desktop

Ouvrez Paramètres → Développeur → Modifier la configuration, ou modifiez le fichier directement :

• 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

Ouvrez la palette de commandes et choisissez Paramètres Cursor → MCP → Ajouter un nouveau serveur MCP global, puis ajoutez :

{
  "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)

Ajoutez ce qui suit à votre 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

Ajoutez à ~/.gemini/settings.json :

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

Configuration

Variables d'environnement

Variable	Requise	Défaut	Description
MAILGUN_API_KEY	Oui	—	Votre clé API Mailgun
MAILGUN_API_REGION	Non	us	Région API : us ou eu
MAILGUN_API_HOSTNAME	Non	(dérivé de la région)	Remplacer le nom d'hôte de l'API (ex. api.eu.mailgun.net). Prend le pas sur la région.
MAILGUN_MCP_TAGS	Non	(tous)	Balises produit séparées par des virgules à activer. Équivalent à --tags. L'option CLI est prioritaire.

Options CLI

Passez les options après le nom du paquet dans le args de votre client (ex. ["-y", "@mailgun/mcp-server", "--tags", "validate,inspect"]).

Option	Description
--tags <list>	Balises produit séparées par des virgules à activer (défaut : toutes). Valides : send, validate, optimize, inspect.
--list-tags	Afficher les valeurs de balises valides et quitter.
--help, -h	Afficher l'aide et quitter.

Filtrage par balise

Vous pouvez limiter les outils que le serveur enregistre à une ou plusieurs balises produit Mailgun. Ceci 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 de capacités d'envoi.

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

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

Via l'option CLI — passez --tags dans le 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 l'emporte si les deux sont présentes) :

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

[!TIP] Exécutez le binaire avec --list-tags pour afficher les valeurs de balises prises en charge, ou --help pour l'aide complète. Les balises inconnues sont rejetées au démarrage avec un message d'erreur clair.

Exemples de prompts

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

[!NOTE] Certains clients MCP nécessitent un forfait payant pour invoquer les 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: alice@example.com, bob@example.com.

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.

Valider une adresse e-mail

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

Vérifier le placement en boîte de réception (Optimiser)

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

Prévisualiser un e-mail (Inspecter)

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

Développement

Exécuter depuis la source

Le serveur est écrit en TypeScript. Cloner, installer, compiler et tester :

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

npm run build compile src/ vers dist/ et copie la spécification OpenAPI intégrée. Pointez votre client MCP vers l'entrée compilée au lieu de npx (utilisez un chemin absolu) :

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

Tests en direct pendant l'édition

Les serveurs MCP sont des processus stdio de longue durée qui ne se rechargent pas à chaud, donc la boucle est : reconstruire à la sauvegarde, puis reconnecter le client pour prendre en compte les changements.

1. Exécutez npm run build une fois pour que dist/openapi.yaml soit en place.

2. Gardez le compilateur TypeScript en cours d'exécution pour reconstruire dist/ à chaque sauvegarde :

   npx tsc --watch
   

3. Pointez un client MCP séparé (ou MCP Inspector, ci-dessous) vers dist/mailgun-mcp.js. Après un changement, redémarrez la session du client MCP pour charger la nouvelle version.

Tests avec MCP Inspector

Le MCP Inspector vous permet d'exercer les outils sans client complet. Compilez d'abord, puis lancez-le contre le serveur compilé :

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

Ouvrez l'interface utilisateur de l'Inspector, cliquez sur Connecter, puis utilisez Lister les outils pour vérifier que le serveur fonctionne. Pour tester un ensemble d'outils filtré, ajoutez des options après le chemin du serveur :

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

Hooks de pré-commit

npm install installe un hook git pre-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 ce changement, exécutez npm install une fois pour installer le hook.

Note sur l'ajout d'endpoints

Lors de l'ajout d'un nouvel endpoint, 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 ne journalise 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 les 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 de prompt

Comme pour tout serveur MCP, un prompt conçu ou contradictoire pourrait tromper l'assistant IA et l'amener à 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 de prompts 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 des outils 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 recourir à 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.